Warning, /graphics/glaxnimate/external/potrace/doc/potracelib.tex is written in an unsupported language. File is not indexed.

 % Copyright (C) 2001-2019 Peter Selinger.
 % This file is part of Potrace. It is licensed under the GNU General
 % Public License. See the file COPYING for details.
 
 \documentclass{article}
 \usepackage{times}
 \usepackage{graphics}
 
 \title{Potrace Library API}
 \author{}
 \date{}
 
 % Alphabetic labels
 {\makeatletter
 \gdef\alphalabels{\def\theenumi{\@alph\c@enumi}\def\labelenumi{(\theenumi)}}}
 
 \begin{document}
 \maketitle
 
 \noindent {\it Copyright \copyright\ 2001-2019 Peter Selinger.  
   This file is part of Potrace. It is licensed under the GNU General
   Public License. See the file COPYING for details. }
 
 \section{Scope}
 
 The Potrace library provides:
 
 \begin{itemize}
 \item tracing, i.e., conversion of bitmaps to a vector representation
   (Bezier curves and straight line segments).
 \end{itemize}
 It does not provide frontend functionality such as:
 
 \begin{itemize}
 \item preparation of bitmaps (e.g.\ reading a bitmap from a file, preparing
   a bitmap by thresholding/scaling/filtering a greyscale image etc)
 \end{itemize}
 And it does not provide backend functionality such as:
 
 \begin{itemize}
 \item post-processing of the vector representation (e.g.\ conversion to a
   file format such as PostScript or SVG, scaling + rotation,
   quantization etc).
 \end{itemize}
 
 \section{Data representation}
 
 \subsection{Bitmaps}\label{ssec-bitmap}
 
 \subsubsection{Coordinate system}
 
 \begin{figure}[t]
 \[ \includegraphics*[0in,0in][3in,1.7in]{potracelib-fig3}
 \]
 \caption{The Potrace coordinate system}\label{fig-coord}
 \end{figure}
 
 For Potrace, a bitmap of size $w\times h$ is embedded in a cartesian
 coordinate system where each pixel takes up the space of one unit
 square. The pixels are positioned so that the {\em corners} of pixels
 (and not their centers) lie at points with integer coordinates, as
 illustrated in Figure~\ref{fig-coord}. The origin of the coordinate
 system is at the {\em lower left} corner of the bitmap. The four
 corners of the bitmaps have coordinates $(0,0)$, $(0,h)$, $(w,h)$, and
 $(w,0)$.
 
 Sometimes we need to refer to a specific pixel (as opposed to a point
 in the plane). When we speak of ``pixel $[i,j]$'', we mean the pixel
 whose corners have coordinates $(i,j)$, $(i,j+1)$, $(i+1,j+1)$,
 $(i+1,j)$ in Potrace's coordinate system. Thus, pixel $[i,j]$ is the
 pixel whose center is at coordinates $(i+0.5, j+0.5)$. To avoid
 confusion, we use square brackets to refer to the pixel $[i,j]$, and
 round brackets to refer to the point $(i,j)$.
 
 \subsubsection{Bitmap representation}
 
 The Potrace library expects bitmaps in the following format, defined
 in potracelib.h:
 
 \begin{verbatim}
 struct potrace_bitmap_s {
   int w, h;          /* width and height, in pixels */
   int dy;            /* scanline offset in words */
   potrace_word *map; /* pixel data, dy*h words */
 };
 typedef struct potrace_bitmap_s potrace_bitmap_t;
 \end{verbatim}
 
 Here, \verb!potrace_word! is an unsigned integer type defined in
 potracelib.h. It is usually equal to a native machine word (i.e., 32
 bits on a 32-bit architecture). In the following explanation, we
 assume that the type \verb!potrace_word! holds $N$ bits.
 
 A bitmap of dimensions $w\times h$ is divided, bottom to top, into $h$
 horizontal scanlines. Each scanline is divided, left to right, into
 blocks of $N$ pixels. Each such block of $N$ pixels is stored as a
 single \verb!potrace_word!, with the leftmost pixels of the block
 corresponding to the most significant bit of the word, and the
 rightmost pixel of the block corresponding to the least significant
 bit of the word.
 
 Pixels that are ``on'' (or ``black'' or ``foreground'') are
 represented by bit value $1$.  Pixels that are ``off'' (of ``white''
 or ``background'') are represented by bit value $0$.
 
 If the number of bits in a scanline is not divisible by $N$, then the
 rightmost word of the scanline is padded on the right with zeros.
 
 The data for scanline $0$ (the bottom-most scanline) begins at
 \verb!map[0]!. The data for scanline $1$ begins at \verb!map[dy]!. The
 data for scanline $2$ begins at \verb!map[2*dy]!, and so forth.  Note
 that $dy$ can be either positive or negative, depending on how an
 application wishes to lay out the image data in memory.
 
 In summary, the pixel with coordinates $[i,j]$ can be accessed by the
 following C formula:
 
 {\small
 \begin{verbatim}
  pixel(i,j) = ((map + j*dy)[i/N] & (1 << (N-1-i%N)) ? 1 : 0.
 \end{verbatim}
 }
 
 \subsubsection{Example}
 
 \begin{figure}
   \[\includegraphics{potracelib-fig2}\]
   \caption{Sample bitmap}\label{fig-bitmap}
 \begin{verbatim}
  w = 36;
  h = 12;
  dy = 2;
  map[22] = 0xfff0fc02;    map[23] = 0x00000000;
  map[20] = 0x7ff1fe02;    map[21] = 0x00000000;
  map[18] = 0x3ff3ff07;    map[19] = 0x00000000;
  map[16] = 0x1ff7ff87;    map[17] = 0x00000000;
  map[14] = 0x0ff7cf8f;    map[15] = 0x80000000;
  map[12] = 0x07f7878f;    map[13] = 0x80000000;
  map[10] = 0x03f7879f;    map[11] = 0xc0000000;
  map[8]  = 0x01f7cf9f;    map[9]  = 0xc0000000;
  map[6]  = 0x00f7ffbf;    map[7]  = 0xe0000000;
  map[4]  = 0x0073ff3f;    map[5]  = 0xe0000000;
  map[2]  = 0x0031fe7f;    map[3]  = 0xf0000000;
  map[0]  = 0x0010fc7f;    map[1]  = 0xf0000000;
 \end{verbatim}
   \caption{Sample bitmap representation}\label{fig-bitmap-rep}
 \end{figure}
 
 Figure~\ref{fig-bitmap} shows an example bitmap of size $36\times 12$.
 Shaded pixels are ``on'' and white pixels are ``off''.
 Figure~\ref{fig-bitmap-rep} shows a possible representation of this
 bitmap in the \verb!potrace_bitmap_t! data structure. Note that the
 data is stored in the \verb!map! array in a bottom-to-top and
 left-to-right fashion.
 
 
 \subsubsection{A remark on byte order}
 
 It is important to keep in mind that bitmaps are stored as arrays of
 words, {\em not} as arrays of bytes. While this distinction makes no
 difference on big-endian architectures, it makes a significant
 difference on little-endian architectures such as the Intel-based
 architecture. For instance, when the integer word 0x1f80fc02 is
 accessed as a byte-array on a little-endian machine, then the bytes
 appear in reverse order 0x02, 0xfc, 0x80, 0x1f. Therefore, special
 care must be taken when converting a bitmap from a byte-based
 format to Potrace's word-based format.
 
 \subsubsection{Coordinate independence}
 
 The vector data that is the output of Potrace is taken with respect
 to the same coordinate system as the input bitmap, i.e., the
 coordinate system from Figure~\ref{fig-coord}. In principle, it is
 immaterial whether an application puts the coordinate origin in the
 bottom-left corner or the top-left corner of an image, as long as it
 interprets the output coordinates in the same way as the input
 coordinates.
 
 However, a reversal of the coordinate system will upset the meaning of
 the words ``clockwise'' and ``counterclockwise'' in the specification
 of vector images below (see Section~\ref{sssec-vector}), and will also
 affect the meaning of Potrace's turnpolicies (see
 Section~\ref{ssec-parameters}). We therefore assume, for definiteness,
 that the coordinate origin is in the {\em lower} left corner.
 Applications that wish to follow a different convention have to
 compensate accordingly.
 
 \subsection{Vector format}
 
 \subsubsection{Points}
 
 A point $(x,y)$ in the Euclidean plane is represented in Potrace by a
 value of type \verb!potrace_dpoint_t!.
 
 \begin{verbatim}
 struct potrace_dpoint_s {
   double x, y;
 };
 typedef struct potrace_dpoint_s potrace_dpoint_t;
 \end{verbatim}
 
 \subsubsection{Segments}
 
 Curves in Potrace are composed of the following two types of segments:
 
 \begin{figure}
   \[\begin{array}{l@{\hspace{1in}}l}
     (a) & (b) \\
     \includegraphics{potracelib-fig4a}&
     \includegraphics{potracelib-fig4b}
   \end{array}
   \]
   \caption{(a) A Bezier curve segment. (b) A corner segment}\label{fig-segment}
 \end{figure}
 
 \begin{itemize}
 \item Bezier curve segments. A Bezier curve segment is given in the
   usual way by a starting point $a$, two control points $u$ and $w$,
   and an endpoint $b$, as shown in Figure~\ref{fig-segment}(a).
 \item Corner segments. A corner segment is given by a starting point
   $a$, a vertex $v$, and an endpoint $b$.  A corner segment is drawn
   as two straight lines: one from $a$ to $v$, and one from $v$ to $b$,
   as shown in Figure~\ref{fig-segment}(b).
 \end{itemize}
 
 \subsubsection{Curves}\label{sssec-curves}
 
 \begin{figure}
   \[\includegraphics{potracelib-fig5}
   \]
   \caption{A closed curve consisting of 4 segments}\label{fig-curve}
 \end{figure}
 
 A curve in Potrace is a sequence of segments, such that the endpoint
 of each segment coincides with the starting point of the next one. All
 curves in Potrace are closed, and therefore the endpoint of the final
 segment also coincides with the starting point of the first one.
 Figure~\ref{fig-curve} shows an example of a curve consisting of 4
 segments: 3 Bezier curve segments and 1 corner segment. For clarity,
 the start- and endpoints of segments have been marked with dots
 ``$\bullet$''.
 
 Curves are represented as values of type \verb!potrace_curve_t!,
 which is defined as follows:
 
 \begin{verbatim}
 struct potrace_curve_s {
   int n;                    /* number of segments */
   int *tag;                 /* array of segment types */
   potrace_dpoint_t (*c)[3]; /* array of control points. */
 };
 typedef struct potrace_curve_s potrace_curve_t;
 \end{verbatim}
 
 Here $n\geq 1$ is the number of segments in the curve. For $i=0,\ldots,n-1$,
 $\verb!tag[i]!$ is the type of the $i$-th segment, which is
 \verb!POTRACE_CURVETO! for a Bezier curve segment and
 \verb!POTRACE_CORNER! for a corner segment. $c$ is an array of size
 $n\times 3$ that holds the control points of the curve segments in
 the following manner:
 \begin{itemize}
 \item If the $i$-th segment is a Bezier curve segment, then
   $\verb!c[i][0]! = u$ and $\verb!c[i][1]! = w$ are the two control
   points of that segment, and $\verb!c[i][2]! = b$ is its endpoint.
 \item If the $i$-th segment is a corner segment, then $\verb!c[i][0]!$
   is unused, $\verb!c[i][1]! = v$ is the vertex of the segment, and
   $\verb!c[i][2]! = b$ is its endpoint.
 \end{itemize}
 
 Note that, since the starting point $a$ of each segment coincides with
 the endpoint $b$ of the preceding segment (and the starting point $a$
 of the first segment coincides with the endpoint $b$ of the last
 segment), there is no need to store the starting points $a$
 explicitly. Also, note that regardless of the type of segment, the
 endpoint of the $i$-th segment is $\verb!c[i][2]!$, and the starting point
 of the $i$-th segment is $\verb!c[i ? i-1 : n-1][2]!$.
 
 The curve from Figure~\ref{fig-curve} is therefore represented
 by the following data:
 \[\begin{array}{llll}
 \verb!n = 4;!\\
 \verb!tag[0] = POTRACE_CURVETO;!\\
 \verb!c[0][0] = !u_0\verb!;!\quad\quad\quad
 \verb!c[0][1] = !w_0\verb!;!\quad
 \verb!c[0][2] = !b_0\verb! = !a_1\verb!;!\\
 \verb!tag[1] = POTRACE_CURVETO;!\\
 \verb!c[1][0] = !u_1\verb!;!\quad\quad\quad
 \verb!c[1][1] = !w_1\verb!;!\quad
 \verb!c[1][2] = !b_1\verb! = !a_2\verb!;!\\
 \verb!tag[2] = POTRACE_CURVETO;!\\
 \verb!c[2][0] = !u_2\verb!;!\quad\quad\quad
 \verb!c[2][1] = !w_2\verb!;!\quad
 \verb!c[2][2] = !b_2\verb! = !a_3\verb!;!\\
 \verb!tag[3] = POTRACE_CORNER;!\\
 \verb!c[3][0] = !{\it unused}\verb!;!\quad
 \verb!c[3][1] = !v_3\verb!;!\quad
 \verb!c[3][2] = !b_3\verb! = !a_0\verb!;!\\
 \end{array}
 \]
 
 \subsubsection{Boundary decomposition of bitonal vector
   images}\label{sssec-boundary}
 
 \begin{figure}
   \[\begin{array}{l@{\hspace{.25in}}l}
     (a) & (b) \\
     \includegraphics{potracelib-fig1a}&
     \includegraphics{potracelib-fig1b}
   \end{array}
   \]
   \caption{(a) A vector image. (b) Its boundary
     decomposition.}\label{fig-vector}
 \end{figure}
 
 In Potrace, a bitonal (i.e. black-and-white) vector image, as in
 Figure~\ref{fig-vector}(a), is decomposed into a collection of closed
 boundary curves, shown in blue and red and labeled $A$--$I$ in
 Figure~\ref{fig-vector}(b).
 
 We introduce some terminology. A closed curve is {\em simple} if it
 does not intersect itself. Each simple closed curve, taken by itself,
 divides the plane into two regions, called the {\em inside} and and
 the {\em outside} of the curve. If $C_1$ and $C_2$ are simple closed
 curves, we say that $C_1$ is {\em contained} in $C_2$, written $C_1 <
 C_2$, if $C_1$ lies entirely within the inside of $C_2$. For example,
 in Figure~\ref{fig-vector}(b), the curves $B$--$E$ are contained in
 $A$, whereas $F$--$I$ are not.
 
 In a decomposition of a vector image as in Figure~\ref{fig-vector}, we
 say that a curve $C_1$ is a {\em child} of $C_2$ if $C_1 < C_2$ and
 there exists no other curve $C_3$ between $C_1$ and $C_2$ (i.e., no
 curve $C_3$ such that $C_1 < C_3 < C_2$). In this case, we also say
 that $C_1$ is a {\em parent} of $C_2$. Since boundary curves do not
 intersect, each curve has at most one parent.  Two curves are said to
 be {\em siblings} if they are either both parentless, or else they
 have a parent in common. Note that the ``child'' relation naturally
 defines a tree structure on the set of curves (more precisely, it
 defines a ``forest'', since there can be more than one root).
 
 For example, in Figure~\ref{fig-vector}(b), the curve $A$ has no
 parent, and has children $B$ and $E$. The curve $E$ has no children,
 and the curve $B$ has children $C$ and $D$. $A$ and $F$ are siblings,
 $B$ and $E$ are siblings, and $C$ and $D$ are siblings. The curves
 from Figure~\ref{fig-vector}(b) form the following forest under the
 ``child'' relation:
 
 \begin{verbatim}
                   A         F
                  / \        |
                 B   E       G
                / \          |
               C   D         H
                             |
                             I
 \end{verbatim}
 
 We can assign each curve a {\em sign} by calling a curve {\em
   positive} if it encloses a ``foreground'' region, and {\em negative}
 if it encloses a ``background'' region (or ``hole''). For example, in
 Figure~\ref{fig-vector}(b), positive curves are shown in blue and
 negative curves in red.
 
 Since foreground and background regions alternate, it follows that the
 sign of curves also alternates, i.e., parentless curves are always
 positive, and all other curves have the opposite sign of their parent.
 It follows that, in the tree structure, curves that appear at even
 levels are positive and those that appear at odd levels are negative.
 In particular, siblings share a common sign.
 
 \subsubsection{Representation of vector images}\label{sssec-vector}
 
 In Potrace, a vector image is represented as a linked collection of
 zero or more structures of type \verb!potrace_path_t!, which is
 defined as follows:
 
 \begin{verbatim}
 struct potrace_path_s {
   int area;                         /* enclosed area */
   int sign;                         /* '+' or '-' */
   potrace_curve_t curve;            /* vector data */
 
   struct potrace_path_s *next;      /* list structure */
 
   struct potrace_path_s *childlist; /* tree structure */
   struct potrace_path_s *sibling;   /* tree structure */
 
   struct potrace_privpath_s *priv;  /* private state */
 };
 typedef struct potrace_path_s potrace_path_t;
 \end{verbatim}
 
 Each such structure holds a single curve, and the structures are
 linked to each other via the \verb!next!, \verb!childlist!, and
 \verb!sibling! pointers.
 
 \begin{itemize}
 
 \item The \verb!sign! field holds the sign of the curve (\verb!'+'! or
   \verb!'-'! in ASCII).
 
 \item The \verb!curve! field contains the curve's vector data as
   described in Section~\ref{sssec-curves}. Potrace additionally
   follows the convention that positive curves run counterclockwise and
   negative curves run clockwise; this facilitates rendering in
   environments (such as PostScript or PDF) that have a ``fill'' rule
   based on winding number.
 
 \item The \verb!area! field gives the approximate magnitude of the
   area enclosed by the curve. (In fact, it is the precise integer area
   of the original untraced ``jaggy'' curve). Some clients use this
   information to improve interactive rendering speeds by ignoring very
   small areas in a first rendering pass. See also the description of
   the \verb!turdsize!  parameter in Section~\ref{ssec-parameters} below.
   
 \item The \verb!priv!  field is used internally by Potrace, and is not
   accessible to applications.
 
 \item The \verb!next! field is used to link all the curves of a given
   vector image into a linked list. Each member points to the next one
   via its \verb!next! field, and the last member of the list has
   \verb!next==NULL!.  The order of the elements of this list is
   unspecified, but is guaranteed to satisfy the following constraints:
   \begin{enumerate}\alphalabels
   \item outer curves appear before inner ones, so if $C_1 < C_2$, then
     $C_2$ always appears sometime before $C_1$ in the linked list, and
   \item each positive curve is immediately followed by all of its
     children.
   \end{enumerate}
   These two constraints make it easy for clients to render the image
   by simply processing the linked list in sequential order.
   Constraint (a) makes it possible to fill each curve with solid black
   or white color, allowing later curves to paint over parts of earlier
   ones.  Constraint (b) further allows a client to fill a positive
   curve, minus its negative children, in a single paint operation,
   leaving a ``hole'' for each of the negative children.
 
 \item The \verb!childlist! and \verb!sibling! fields define a forest
   structure on the set of curves, which can be used independently of
   the linked list structure.  For each curve, \verb!childlist! is a
   pointer to its first child, or \verb!NULL! if there are no children.
   Also, \verb!sibling! is a pointer to the next sibling, or
   \verb!NULL!  if there are no further siblings.  The relative order
   of siblings is unspecified. The root node of the tree structure
   always coincides with the root node of the linked list structure.
 \end{itemize}
 
 An image consisting of zero curves is represented as a \verb!NULL! pointer.
 
 \subsubsection{Intersecting curves}
 
 While in the above discussion we have assumed a set of
 non-intersecting curves, in practice it can happen that the curves
 output by Potrace intersect slightly. Clients should therefore
 carefully choose their rendering parameters (e.g., the non-zero
 winding number rule is preferable to the odd winding number rule) to
 avoid undesirable artifacts.
 
 \subsubsection{Example}
 
 The image from Figure~\ref{fig-vector} can be represented by the
 pointer \verb!plist!, where {\tt A}--{\tt I} are structures
 of type \verb!potrace_path_t!, as follows.  We do not show the
 \verb!area! and \verb!curve! fields.
 {\small
 \begin{verbatim}
  potrace_path_t *plist = &A;
 
  A.sign = '+';       B.sign = '-';       E.sign = '-';
  A.next = &B;        B.next = &E;        E.next = &C;
  A.childlist = &B;   B.childlist = &C;   E.childlist = NULL;
  A.sibling = &F;     B.sibling = &E;     E.sibling = NULL;
 
  C.sign = '+';       D.sign = '+';       F.sign = '+';
  C.next = &D;        D.next = &F;        F.next = &G;
  C.childlist = NULL; D.childlist = NULL; F.childlist = &G;
  C.sibling = &D;     D.sibling = NULL;   F.sibling = NULL;
 
  G.sign = '-';       H.sign = '+';       I.sign = '-';
  G.next = &H;        H.next = &I;        I.next = NULL;
  G.childlist = &H;   H.childlist = &I;   I.childlist = NULL;
  G.sibling = NULL;   H.sibling = NULL;   I.sibling = NULL;
 \end{verbatim}
 }
 
 \subsection{Tracing parameters}\label{ssec-parameters}
 
 The tracing operation of Potrace is controlled by a small number of
 parameters. The parameter structure is defined in potracelib.h as:
 
 \begin{verbatim}
 struct potrace_param_s {
   int turdsize;        
   int turnpolicy;      
   double alphamax;     
   int opticurve;       
   double opttolerance; 
   potrace_progress_t progress; 
 };
 typedef struct potrace_param_s potrace_param_t;
 \end{verbatim}
 
 For most practical purposes, the default parameters give excellent
 results. The function \verb!potrace_param_default()! (see
 Section~\ref{5c}) returns the set of default parameters. Applications
 must always start from these default parameters before changing any
 parameters. This will increase backward compatibility in case
 additional parameters are added in the future.
 
 \subsubsection{Turdsize}
 
 \begin{figure}
 \[\begin{array}{l@{\hspace{.5in}}l}
   \textrm{\rm Before:} & \textrm{\rm After:}\\
   \includegraphics{potracelib-fig6a}&
   \includegraphics{potracelib-fig6b}
 \end{array}
 \]
 \caption{Despeckling with turdsize=3.}\label{fig-turdsize}
 \end{figure}
 
 The \verb!turdsize! parameter can be used to ``despeckle'' the bitmap
 to be traced, by removing all curves whose enclosed area is below the
 given threshold. Figure~\ref{fig-turdsize} shows the result of
 applying turdsize=3 to a bitmap. The current default for the turdsize
 parameter is 2; its useful range is from 0 to infinity.
 
 \subsubsection{Turnpolicy}
 
 \begin{figure}
 \[\includegraphics{potracelib-fig8}\]
 \caption{Path decomposition}\label{fig-turns}
 \end{figure}
 
 The turnpolicy parameter determines how to resolve ambiguities during
 decomposition of bitmaps into paths. The ambiguity arises in the last
 situation shown in Figure~\ref{fig-turns}. The possible choices for
 the \verb!turnpolicy! parameter are:
 \begin{itemize}
 \item \verb!POTRACE_TURNPOLICY_BLACK!: prefers to connect black
   (foreground) components.
 \item \verb!POTRACE_TURNPOLICY_WHITE!: prefers to connect white
   (background) components.
 \item \verb!POTRACE_TURNPOLICY_LEFT!: always take a left turn.
 \item \verb!POTRACE_TURNPOLICY_RIGHT!: always take a right turn.
 \item \verb!POTRACE_TURNPOLICY_MINORITY!: prefers to connect the color
   (black or white) that occurs least frequently in a local
   neighborhood of the current position.
 \item \verb!POTRACE_TURNPOLICY_MAJORITY!: prefers to connect the color
   (black or white) that occurs most frequently in a local neighborhood
   of the current position.
 \item \verb!POTRACE_TURNPOLICY_RANDOM!: choose pseudo-randomly.
 \end{itemize}
 
 The current default policy is \verb!POTRACE_TURNPOLICY_MINORITY!, which tends
 to keep visual lines connected.
 
 \subsubsection{Alphamax}
 
 \begin{figure}
 \[\begin{array}{ccccc}
 \includegraphics{potracelib-fig7-00}&
 \includegraphics{potracelib-fig7-06}&
 \includegraphics{potracelib-fig7-10}&
 \includegraphics{potracelib-fig7-12}&
 \includegraphics{potracelib-fig7-13}\\
 \alpha_{max}=0.0&
 \alpha_{max}=0.6&
 \alpha_{max}=1.0&
 \alpha_{max}=1.2&
 \alpha_{max}=1.3
 \end{array}
 \]
 \caption{The alphamax parameter}\label{fig-alphamax}
 \end{figure}
 
 The \verb!alphamax! parameter is a threshold for the detection of
 corners. It controls the smoothness of the traced curve, as shown in
 Figure~\ref{fig-alphamax}. The current default is 1.0.  The useful range of
 this parameter is from 0.0 (polygon) to 1.3334 (no corners).
 
 \subsubsection{Opticurve and opttolerance}
 
 The \verb!opticurve! parameter is a boolean flag that controls whether
 Potrace will attempt to ``simplify'' the final curve by reducing the
 number of Bezier curve segments. Opticurve=1 turns on optimization,
 and opticurve=0 turns it off. The current default is on. 
 
 The \verb!opttolerance! parameter defines the amount of error allowed
 in this simplification. The current default is 0.2. Larger values tend to
 decrease the number of segments, at the expense of less accuracy.  The
 useful range is from 0 to infinity, although in practice one would
 hardly choose values greater than 1 or so. For most purposes, the
 default value is a good tradeoff between space and accuracy.
 
 \subsubsection{Progress reporting}
 
 Since tracing a large bitmap can be time consuming, Potrace has the
 option of reporting progress to the calling application. This is
 typically used in interactive applications to implement a progress
 bar. Progress reporting is controlled by the \verb!progress!
 parameter, which is a structure of type \verb!potrace_progress_t!,
 defined as follows:
 
 \begin{verbatim}
 struct potrace_progress_s {
   void (*callback)(double progress, void *privdata);
   void *data;      
   double min, max; 
   double epsilon;      
 };
 typedef struct potrace_progress_s potrace_progress_t;
 \end{verbatim}
 
 If \verb!callback! is not NULL, then progress reporting is enabled.
 In this case, \verb!callback! is the address of a function to be
 called for progress reports, and \verb!data! is a pointer to that
 function's private data.  Progress reports take the form of a function
 call \verb!callback(d, data)!, where \verb!d! is a number representing
 the amount of relative progress in the range
 \verb!min!\ldots\verb!max!. 
 
 The parameter \verb!epsilon! is a hint that tells Potrace what amount of
 progress the application considers ``too small to report''. Whenever
 convenient, Potrace will feel free to suppress progress reports if the
 increment since the previous report has been less than \verb!epsilon!.  As
 a special case, if $\verb!epsilon!=0$, then the maximal number of progress
 reports are sent. In any case, the application should handle progress
 reports very efficiently, as there may be a large number of reports. 
 
 The defaults are $\verb!callback!=\textrm{NULL}$,
 $\verb!data!=\textrm{NULL}$, $\verb!min!=0.0$, $\verb!max!=1.0$, and
 $\verb!epsilon!=0$.
 
 \subsection{Potrace state}\label{4}
 
 A Potrace state holds the result of a tracing operation. It is
 defined as follows:
 
 \begin{verbatim}
 struct potrace_state_s {
   int status;
   potrace_path_t *plist;            /* vector data */
 
   struct potrace_privstate_s *priv; /* private state */
 };
 typedef struct potrace_state_s potrace_state_t;
 \end{verbatim}
 
 The fields are as follows:
 \begin{itemize}
 \item The \verb!status! field is either \verb!POTRACE_STATUS_OK!, to
   indicate that the tracing operation was successful, or
   \verb!POTRACE_STATUS_INCOMPLETE!, to indicate that it was
   unsuccessful.
 \item In the event of success, \verb!plist! points to the
   representation of the bitonal traced vector image as described in
   Section~\ref{sssec-vector}.  In the event of failure, \verb!plist!
   points to a data structure whose properties are undefined, except
   that the Potrace state can still be freed with \verb!potrace_state_free()!.
 \item The \verb!priv! field is used internally by Potrace, and is not
   accessible by applications.
 \end{itemize}
 
 \section{API functions}\label{5}
 
 There is no global or static state in potracelib; all API functions
 are reentrant and thread-safe.
 
 \subsection{potrace\_trace}\label{5a}
 
 {\small
 \begin{verbatim}
 potrace_state_t *potrace_trace(const potrace_param_t *param,
                                const potrace_bitmap_t *bm);
 \end{verbatim}
 }
 
 \noindent Inputs: 
 \begin{itemize}
 \item \verb!bm!: a bitmap (see Section~\ref{ssec-bitmap}).
 \item \verb!param!: a set of tracing parameters (see
   Section~\ref{ssec-parameters}).
 \end{itemize}
 
 \noindent Output:
 \begin{itemize}
 \item a Potrace state (see Section~\ref{4}). 
 \end{itemize}
 
 This function attempts to trace the given bitmap using the given
 tracing parameters. In the event of success, it returns a valid
 Potrace state with the \verb!status! field set to
 \verb!POTRACE_STATUS_OK!.  In the event of failure, it sets
 \verb!errno! to an error number, and either returns \verb!NULL!, or
 else it returns an incomplete Potrace state, which by definition has
 the status field set to \verb!POTRACE_STATUS_INCOMPLETE!. Any Potrace
 state returned by \verb!potrace_trace()! (whether it is valid or
 invalid) can be freed using the \verb!potrace_state_free()! function
 below.
 
 \subsection{potrace\_state\_free}\label{5b}
 
 \begin{verbatim}
 void potrace_state_free(potrace_state_t *st);
 \end{verbatim}
 
 \noindent Input:
 \begin{itemize}
 \item \verb!st!: a Potrace state previously returned by
   \verb!potrace_trace()!.
 \end{itemize}
 
 This function frees the memory and other resources (if any) associated
 with the Potrace state.
 
 \subsection{potrace\_param\_default}\label{5c}
 
 \begin{verbatim}
 potrace_param_t *potrace_param_default();
 \end{verbatim}
 
 \noindent Output:
 \begin{itemize}
 \item a set of tracing parameters (see Section~\ref{ssec-parameters}). 
 \end{itemize}
 
 This function returns a fresh set of tracing parameters, initialized
 to defaults.  Applications must always use this function to create an
 object of type \verb!potrace_param_t!, and they must always start from
 the default parameters before modifying any parameters.  This will
 help increase backward compatibility when additional parameters are
 added in the future. The parameter set returned by this function can
 later be freed by \verb!potrace_param_free()!.
 
 \subsection{potrace\_param\_free()}\label{5d}
 
 \begin{verbatim}
 void potrace_param_free(potrace_param_t *p);
 \end{verbatim}
 
 \noindent Input:
 \begin{itemize}
 \item tracing parameters previously returned by
   \verb!potrace_param_default()!.
 \end{itemize}
 
 This function frees the memory occupied by a set of tracing parameters
 as returned by \verb!potrace_param_default()!. Only the fields
 initialized by Potrace are freed, not any fields set by the
 application itself (such as \verb!progress.data!).
 
 \subsection{potrace\_version()}\label{5e}
 
 \begin{verbatim}
 const char *potrace_version();
 \end{verbatim}
 
 This function returns a static human-readable text string identifying
 this version of potracelib.
 
 \end{document}