How to let text flow around irregular-shaped graphics in ConTeXt?

Question

I have some illustrations which I need to scan and place within a document. The illustrations come in various shapes, with no straight edges, and are bound by lots empty white space, e.g.:

 __________________
|                  |
|    *  *          |
|   ******         |
|   ******     *   |
|    ****     *    |
|     *********    |
|      ********    |
|      * *  * *    | 
|     *  *  * *    |
|__________________|

I would like to be able to allow the text of the document to fit more closely to the shape, for e.g.:

|           This is the story |
|    *  *     of a cat named  |
|   ******        Cat who li- |
|   ******     *  ked to eat  |
|    ****     *  mice. One d- |
|     *********  ay while wa- |
|      ********  lking throu- |
|      * *  * *  gh the fore- |
|     *  *  * *  st, Cat fou- |
|                nd a family  |
| of mice who lived in a hol- |
| llow tree.                  |

How can I place such an irregularly shaped graphic within my document?

Answer 1

What you're after is the build_parshape macro and the shapetext environment. build_parshape takes a MetaPost path as an argument and aligns the text to the path. shapetext, well… the name already reveals what it's doing. This is detailed in the MetaPost manual chapter 10 Typesetting in MetaPost.

I don't know of a simple way to extract the shape of an arbitrary graphic to a MetaPost path. In this example I've done it manually. Take an image, overlay a grid and note the coordinates of interesting points. That are the points f, b, d in the example.

%% provides the shapetext environment
\useMPlibrary [txt]

%% locate sample images in texmf tree
\setupexternalfigures [location=default]

\startuseMPgraphic{parshape}
  path fin;

  h := 12cm; % height
  w := 14cm; % width
  pair f; f := (8cm, h-3cm);  % feet corner
  pair b; b := (6cm, h-6cm);  % belly corner
  pair d; d := (2cm, 1cm);    % head corner

  pair p[];
  p0  := origin;
  p1  := (w, 0);
  p2  := (w, h);
  p3  := (xpart f, h);
  p4  := f;
  p5  := (xpart b, ypart f);
  p6  := b;
  p7  := (xpart f, ypart b);
  p8  := (xpart f, (ypart b)-2cm);
  p9  := d;
  p10 := (0, ypart d);

  fin := p0--p1--p2--p3--p4--p5--p6--p7--p8--p9--p10--cycle;

  build_parshape(fin,0,0,0,\baselinedistance, \strutheight,\strutdepth,\strutheight) ;
\stopuseMPgraphic

\defineoverlay [parshape] [\useMPgraphic{parshape}]
\definelayer   [image]
\setlayer      [image]    {\externalfigure[cow][height=8cm, orientation=90]}

\starttext
  \startshapetext [parshape]
    \input zapf
    \input zapf
  \stopshapetext

  \framed [background=image,frame=off] {\getshapetext}
\stoptext

Answer 2

This answer has two parts, and I fear that you might not like any of them.

The first part is: avoid such text flows, even if you find a convenient way to do it. I would say that such an individually tuned text flow might be useful to illustrate a specific effect. But in general, it is a bad practice which should be avoided whenever possible. If you need help with side-by-side blocks of text/graphics (without individual alignment), you might post a separate question about that one.

The second part is: even if you decide to ignore my advice, you have two challenges. The first is to tell TeX about the white space in your graphics. This is most likely something that you have to do manually, by means of trial-and-error. The second challenge is to tell TeX how to align the paragraph in question. This is where I might be able to help you.

I am aware of the TeX primitive \parshape. It allows you to shape all following lines of the next paragraph with a high degree of freedom. Here is an example (I created it some time ago because I found it funny). It is a quote of the statistics guy Youden:

\documentclass{standalone}

\begin{document}

\begin{minipage}{12cm}%
{\let\unit=\linewidth
\parshape 15 %  means: # pairs of (LEFT MARGIN, LENGTH) follow
0.440\unit      0.119\unit
0.413\unit      0.172\unit
0.392\unit      0.214\unit
0.373\unit      0.252\unit
0.355\unit      0.288\unit
0.338\unit      0.323\unit
0.321\unit      0.357\unit
0.303\unit      0.392\unit
0.285\unit      0.428\unit
0.266\unit      0.466\unit
0.245\unit      0.508\unit
0.222\unit      0.555\unit
0.195\unit      0.609\unit
0.160\unit      0.679\unit
0.107\unit      0.784\unit
%0.05\unit      0.95\unit% these numbers fill the LAST line.
%\noindent\hbox to0.119\unit{\hfil The\hfil} 
The
Normal Law of Error Stands out in the Experience of mankind as  one  of  the  broadest Generalizations  of  natural Philosophy and it serves as the Guiding instrument in researches in the Physical and social sciences and in medicine agriculture and engineering and it is an indispensable tool for the analysis and the interpretation of the basic data obtained by observation and experiment.
%\dotfill

}
\end{minipage}

\end{document}

The trick is to write \parshape <N> where <N> is the number of following pairs <left margin> <length>. Each pair defines one line to shape. I computed these lines by means of a simple tool.

Note that the paragraph as such is entirely unformatted.