\section{chain\_\-provisional.c File Reference}
\label{chain__provisional_8c}\index{chain_provisional.c@{chain\_\-provisional.c}}
Interpolated measurements for insertion and removal of ring boundaries. 

{\tt \#include $<$sadie.h$>$}\par
{\tt \#include $<$math.h$>$}\par
{\tt \#include \char`\"{}junkmath.h\char`\"{}}\par
{\tt \#include \char`\"{}Sadie\_\-Index.h\char`\"{}}\par
{\tt \#include \char`\"{}logerr.h\char`\"{}}\par
{\tt \#include \char`\"{}chain\_\-provisional.h\char`\"{}}\par
\subsection*{Classes}
\begin{CompactItemize}
\item 
struct {\bf Provisionalrings}
\begin{CompactList}\small\item\em Measurements for rings affected by an added or removed boundary (2 at most). \item\end{CompactList}\item 
struct {\bf Boundbracket}
\begin{CompactList}\small\item\em Used for interpolating new points between old points and boundaries. \item\end{CompactList}\item 
struct {\bf Roiframe}
\begin{CompactList}\small\item\em Holds a summary of the region of interest coordinate frame. \item\end{CompactList}\end{CompactItemize}
\subsection*{Defines}
\begin{CompactItemize}
\item 
\#define {\bf MAXIMUM\_\-DISTANCE}\ HUGE\_\-VAL\label{chain__provisional_8c_a0}

\begin{CompactList}\small\item\em A constant larger than any measurable distance. \item\end{CompactList}\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef {\bf Provisionalrings} $\ast$ {\bf provisionalringsp\_\-t}\label{chain__provisional_8c_a1}

\begin{CompactList}\small\item\em Pointer to a container of messy easurement and boundary data. \item\end{CompactList}\item 
typedef {\bf Boundbracket} $\ast$ {\bf boundbracketp\_\-t}\label{chain__provisional_8c_a2}

\begin{CompactList}\small\item\em Pointer to the pairing of a point and a boundary. \item\end{CompactList}\item 
typedef {\bf Roiframe} $\ast$ {\bf roiframep\_\-t}\label{chain__provisional_8c_a3}

\begin{CompactList}\small\item\em Pointer to the summary of the ROI coordinate frame. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
void {\bf provisionalrings\_\-destruct} (void $\ast$data)
\begin{CompactList}\small\item\em Destroy a provisional measurement collection and all its sub-structures. \item\end{CompactList}\item 
void {\bf scale\_\-boundary} (BOUNDER $\ast$bound, double scale)
\begin{CompactList}\small\item\em Scale the coordinate representation of a boundary by a scalar multiplier. \item\end{CompactList}\item 
LIST\_\-NODE $\ast$ {\bf make\_\-chain} (BOUNDER $\ast$bound)
\begin{CompactList}\small\item\em Generate a chain-coded boundary from a coordinate boundary representation. \item\end{CompactList}\item 
void {\bf chain\_\-extrapolate} ({\bf IMAGE\_\-BYTE} $\ast$mimage, MOSAIC\_\-INDEX $\ast$mindex, double scale, double x, double y, double orig\_\-x, double orig\_\-y, double orig\_\-phi, LIST\_\-NODE $\ast$guide, BOUNDBOX\_\-LIST box, double $\ast$width, {\bf PROFILE\_\-LIST} $\ast$prof, LIST\_\-NODE $\ast$$\ast$extrapolated, LIST\_\-NODE $\ast$$\ast$small\_\-extrapolated)
\begin{CompactList}\small\item\em Copy an existing chain-coded boundary, and measure the ring thus defined. \item\end{CompactList}\item 
void {\bf chain\_\-collapse} ({\bf IMAGE\_\-BYTE} $\ast$mimage, MOSAIC\_\-INDEX $\ast$mindex, LIST\_\-NODE $\ast$inner, LIST\_\-NODE $\ast$outer, double $\ast$width, {\bf PROFILE\_\-LIST} $\ast$prof)
\begin{CompactList}\small\item\em Measure the new ring formed by deleting the common boundary of two rings. \item\end{CompactList}\item 
int {\bf provisional\_\-point\_\-in\_\-roi} (MOSAIC\_\-INDEX $\ast$mindex, double x, double y)
\begin{CompactList}\small\item\em Test if coordinates fall within the region of interest in the image mosaic. \item\end{CompactList}\item 
double {\bf provisional\_\-point\_\-distance} (double x, double y, LIST\_\-NODE $\ast$boundary)
\begin{CompactList}\small\item\em Find the minimum distance between a point and a chain-coded boundary. \item\end{CompactList}\item 
void {\bf chain\_\-interpolate} ({\bf IMAGE\_\-BYTE} $\ast$mimage, MOSAIC\_\-INDEX $\ast$mindex, double scale, double x, double y, LIST\_\-NODE $\ast$inner, LIST\_\-NODE $\ast$outer, BOUNDBOX\_\-LIST box, double $\ast$w\_\-before, {\bf PROFILE\_\-LIST} $\ast$prof\_\-before, double $\ast$w\_\-after, {\bf PROFILE\_\-LIST} $\ast$prof\_\-after, LIST\_\-NODE $\ast$$\ast$interpolated, LIST\_\-NODE $\ast$$\ast$small\_\-interpolated)
\begin{CompactList}\small\item\em Interpolate a new chain-coded ring boundary between two existing ones. \item\end{CompactList}\item 
int {\bf provisional\_\-insert} (char $\ast$doc, int provbnum, {\bf IMAGE\_\-BYTE} $\ast$mimage, MOSAIC\_\-INDEX $\ast$mindex, double scale, double x, double y, LIST\_\-NODE $\ast$inner, LIST\_\-NODE $\ast$outer)
\begin{CompactList}\small\item\em Insert a new boundary in the chain map between two existing boundaries. \item\end{CompactList}\item 
int {\bf provisional\_\-delete} (char $\ast$doc, int provbnum, {\bf IMAGE\_\-BYTE} $\ast$mimage, MOSAIC\_\-INDEX $\ast$mindex, LIST\_\-NODE $\ast$inner, LIST\_\-NODE $\ast$deleted, LIST\_\-NODE $\ast$outer, LIST\_\-NODE $\ast$small)
\begin{CompactList}\small\item\em Delete an existing chain-coded boundary. \item\end{CompactList}\item 
int {\bf provisional\_\-missing} (char $\ast$doc, int provbnum, {\bf IMAGE\_\-BYTE} $\ast$mimage, MOSAIC\_\-INDEX $\ast$mindex, BOUNDBOX\_\-LIST bbox, LIST\_\-NODE $\ast$guide, LIST\_\-NODE $\ast$small)
\begin{CompactList}\small\item\em Insert a missing ring after an existing chain-coded boundary. \item\end{CompactList}\item 
int {\bf provisional\_\-extend} (char $\ast$doc, int provbnum, {\bf IMAGE\_\-BYTE} $\ast$mimage, MOSAIC\_\-INDEX $\ast$mindex, double scale, double x, double y, LIST\_\-NODE $\ast$initial, LIST\_\-NODE $\ast$final)
\begin{CompactList}\small\item\em Extend the list of chain-coded boundaries by a new boundary at the end. \item\end{CompactList}\item 
int {\bf provisional\_\-check} (double x, double y, LIST\_\-NODE $\ast$inner, LIST\_\-NODE $\ast$outer)
\begin{CompactList}\small\item\em Check if a point lies between two chain-coded boundaries. \item\end{CompactList}\item 
int {\bf have\_\-provisional\_\-changes} (char $\ast$doc, char $\ast$pname)
\begin{CompactList}\small\item\em Test if there are valid modified data in the provisional measurements. \item\end{CompactList}\item 
LIST\_\-NODE $\ast$ {\bf get\_\-provisional\_\-full\_\-chain} (char $\ast$doc, char $\ast$pname)
\begin{CompactList}\small\item\em Recover the full-resolution chain-coded boundary from the hash table. \item\end{CompactList}\item 
LIST\_\-NODE $\ast$ {\bf get\_\-provisional\_\-small\_\-chain} (char $\ast$doc, char $\ast$pname)
\begin{CompactList}\small\item\em Recover the downsampled chain-coded boundary from the hash table. \item\end{CompactList}\item 
int {\bf get\_\-provisional\_\-insert\_\-point} (char $\ast$doc, char $\ast$pname)
\begin{CompactList}\small\item\em Recover the insertion point in the list of chain-coded boundaries. \item\end{CompactList}\item 
int {\bf find\_\-provisional\_\-widths} (char $\ast$doc, char $\ast$pname, double $\ast$$\ast$widthhandle)
\begin{CompactList}\small\item\em Find the array of provisional total ring widths in the hash table. \item\end{CompactList}\item 
int {\bf find\_\-provisional\_\-profiles} (char $\ast$doc, char $\ast$pname, {\bf PROFILE\_\-LIST} $\ast$$\ast$profhandle)
\begin{CompactList}\small\item\em Find the array of provisional brightness profiles in the hash table. \item\end{CompactList}\item 
int {\bf find\_\-provisional\_\-diff\_\-profiles} (char $\ast$doc, char $\ast$pname, {\bf PROFILE\_\-LIST} $\ast$$\ast$diffprofhandle)
\begin{CompactList}\small\item\em Find the array of provisional differenced brightness profiles. \item\end{CompactList}\item 
int {\bf find\_\-provisional\_\-earlywidths} (char $\ast$doc, char $\ast$pname, double $\ast$$\ast$earlywidthhandle)
\begin{CompactList}\small\item\em Find the array of provisional earlywood widths in the hash table. \item\end{CompactList}\item 
int {\bf find\_\-provisional\_\-latewidths} (char $\ast$doc, char $\ast$pname, double $\ast$$\ast$latewidthhandle)
\begin{CompactList}\small\item\em Find the array of provisional latewood widths in the hash table. \item\end{CompactList}\item 
int {\bf find\_\-provisional\_\-boundbox} (char $\ast$doc, char $\ast$pname, BOUNDBOX\_\-LIST $\ast$boundboxhandle)
\begin{CompactList}\small\item\em Find the bounding box for the provisional ring. \item\end{CompactList}\end{CompactItemize}
\subsection*{Variables}
\begin{CompactItemize}
\item 
{\bf sad\_\-doclistp\_\-t} {\bf global\_\-doclist}\label{chain__provisional_8c_a4}

\begin{CompactList}\small\item\em Hash table storing arbitrary data (including {\bf Provisionalrings}{\rm (p.\,\pageref{structProvisionalrings})} structures). \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Interpolated measurements for insertion and removal of ring boundaries. 

This provides several operations to support the operations that add or remove ring boundaries. They generate new boundaries by either interpolating between a pair of previously detected boundaries close to a specified position (e.g., a mouse click on an image), or by taking the long axis of the region of interest within which the other boundaries lie and placing a copy of one of these previously detected boundaries at a position along this axis close to the secified position. We use the Sadie\_\-Index hash table implementation to store the measurements generated or modified by the boundary insertions and deletions, and provide a complete range of functions to retrieve these data while hiding the messy details of the implementation.

\begin{Desc}
\item[Author:]University of Arizona Digital Image Analysis Lab \end{Desc}
\begin{Desc}
\item[Date:]2004 \end{Desc}
\begin{Desc}
\item[Version:]\begin{Desc}
\item[Id]{\bf chain\_\-provisional.c}{\rm (p.\,\pageref{chain__provisional_8c})},v 1.4 2004/11/19 19:11:11 mmunro Exp \end{Desc}
\end{Desc}


\subsection{Function Documentation}
\index{chain_provisional.c@{chain\_\-provisional.c}!chain_collapse@{chain\_\-collapse}}
\index{chain_collapse@{chain\_\-collapse}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void chain\_\-collapse ({\bf IMAGE\_\-BYTE} $\ast$ {\em mimage}, MOSAIC\_\-INDEX $\ast$ {\em mindex}, LIST\_\-NODE $\ast$ {\em inner}, LIST\_\-NODE $\ast$ {\em outer}, double $\ast$ {\em width}, {\bf PROFILE\_\-LIST} $\ast$ {\em prof})}\label{chain__provisional_8c_a26}


Measure the new ring formed by deleting the common boundary of two rings. 

Although we will generally use this to derive a new set of measurements for the single ring formed from two rings by the deletion of their common boundary, in principle it is just a general single-ring measurement function, analogous to a single iteration of the main loop in the CHAIN\_\-RINGWIDTHS function. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em mimage}]points to the mosaic image. \item[{\em mindex}]points to the index to the mosaic image. \item[{\em inner}]points to the first pre-existing chaincoded boundary. \item[{\em outer}]points to the second pre-existing chaincoded boundary. \item[{\em width}]will point to the total ring width for the new ring. \item[{\em prof}]will point to the brightness profile for the new ring. \end{description}
\end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!chain_extrapolate@{chain\_\-extrapolate}}
\index{chain_extrapolate@{chain\_\-extrapolate}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void chain\_\-extrapolate ({\bf IMAGE\_\-BYTE} $\ast$ {\em mimage}, MOSAIC\_\-INDEX $\ast$ {\em mindex}, double {\em scale}, double {\em x}, double {\em y}, double {\em orig\_\-x}, double {\em orig\_\-y}, double {\em orig\_\-phi}, LIST\_\-NODE $\ast$ {\em guide}, BOUNDBOX\_\-LIST {\em box}, double $\ast$ {\em width}, {\bf PROFILE\_\-LIST} $\ast$ {\em prof}, LIST\_\-NODE $\ast$$\ast$ {\em extrapolated}, LIST\_\-NODE $\ast$$\ast$ {\em small\_\-extrapolated})}\label{chain__provisional_8c_a25}


Copy an existing chain-coded boundary, and measure the ring thus defined. 

Taking the region of interest within the image mosaic, the coordinates of the new boundary position, and an existing chain-coded boundary, we generate a new boundary as copy of the existing one, translated along the region of interest so that it falls near the specified coordinates. We transcribe the old chain-coded boundary to a representation that records the absolute coordinates of each point in continuous space (rather than the discrete relative steps of the chain code): a BOUNDER structure. The new boundary is initially also a BOUNDER structure, and all the ring measurements are derived from this pair of BOUNDER representations. We convert the new boundary to a chain-code representation (at two different resolutions), and simply discard the BOUNDER structures, which isn't very elegant. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em mimage}]points to the mosaic image. \item[{\em mindex}]points to the index to the mosaic image. \item[{\em scale}]the downsampling factor for the low-resolution chaincode. \item[{\em x}]the horizontal coordinate of the new boundary location. \item[{\em y}]the vertical coordinate of the new boundary location. \item[{\em orig\_\-x}]the x coordinate of the region of interest origin. \item[{\em orig\_\-y}]the y coordinate of the region of interest origin. \item[{\em orig\_\-phi}]the angle of the long axis of the ROI. \item[{\em guide}]points to the chaincoded existing boundary. \item[{\em box}]will point to the bounding box for the new boundary. \item[{\em width}]will point to the total ring width for the new ring. \item[{\em prof}]will point to the brightness profile for the new ring. \item[{\em extrapolated}]will point to the new chain-coded boundary. \item[{\em small\_\-extrapolated}]will point to the new boundary, downsampled. \end{description}
\end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!chain_interpolate@{chain\_\-interpolate}}
\index{chain_interpolate@{chain\_\-interpolate}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void chain\_\-interpolate ({\bf IMAGE\_\-BYTE} $\ast$ {\em mimage}, MOSAIC\_\-INDEX $\ast$ {\em mindex}, double {\em scale}, double {\em x}, double {\em y}, LIST\_\-NODE $\ast$ {\em inner}, LIST\_\-NODE $\ast$ {\em outer}, BOUNDBOX\_\-LIST {\em box}, double $\ast$ {\em w\_\-before}, {\bf PROFILE\_\-LIST} $\ast$ {\em prof\_\-before}, double $\ast$ {\em w\_\-after}, {\bf PROFILE\_\-LIST} $\ast$ {\em prof\_\-after}, LIST\_\-NODE $\ast$$\ast$ {\em interpolated}, LIST\_\-NODE $\ast$$\ast$ {\em small\_\-interpolated})}\label{chain__provisional_8c_a32}


Interpolate a new chain-coded ring boundary between two existing ones. 

Given two existing chain-coded boundaries and the coordinates of a point, we construct a new boundary by interpolation between the boundaries, taking the point coordinates as an approximate guide to its position. As normally used, the new boundary will split a previously measured ring in two, so there will be not just one set of modified ring measurements, but two. We transcribe the existing chain-coded boundaries to a representation that use the absolute coordinates of each point (BOUNDER structures); when first constructed, the new boundary uses the same representation, however the new boundary gets converted to a chain-coded representation (at two different resolutions), which along with the new measurements are the only data output from this function. The original BOUNDER representation of the interpolated boundary lacks the accurate information about local perpendicular directions needed for the width measurement, so we wastefully discard it after creating the chain-coded boundary, re-generate a new BOUNDER from the chain code, and use this for the measurements, before discarding it as well. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em mimage}]points to the mosaic image. \item[{\em mindex}]points to the index to the mosaic image. \item[{\em scale}]the downsampling factor for the low-resolution chaincode. \item[{\em x}]the horizontal coordinate of the new boundary location. \item[{\em y}]the vertical coordinate of the new boundary location. \item[{\em inner}]points to the first pre-existing chaincoded boundary. \item[{\em outer}]points to the second pre-existing chaincoded boundary. \item[{\em box}]will point to the bounding box for the new boundary. \item[{\em width}]will point to the total ring width for the new rings. \item[{\em prof}]will point to the brightness profile for the new rings. \item[{\em interpolated}]will point to the new chain-coded boundary. \item[{\em small\_\-interpolated}]will point to the new boundary, downsampled. \end{description}
\end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!find_provisional_boundbox@{find\_\-provisional\_\-boundbox}}
\index{find_provisional_boundbox@{find\_\-provisional\_\-boundbox}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int find\_\-provisional\_\-boundbox (char $\ast$ {\em doc}, char $\ast$ {\em pname}, BOUNDBOX\_\-LIST $\ast$ {\em boundboxhandle})}\label{chain__provisional_8c_a50}


Find the bounding box for the provisional ring. 

Although this could be the head of a list of bounding boxes in a completely general case, here we're assuming it's the single box for one ring boundary. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em pname}]a string identifying the set of provisional measrements. \item[{\em boundboxhandle}]will get set to a pointer to bounding box. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of valid boxes (should be exactly 1, or 0 if an error). \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!find_provisional_diff_profiles@{find\_\-provisional\_\-diff\_\-profiles}}
\index{find_provisional_diff_profiles@{find\_\-provisional\_\-diff\_\-profiles}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int find\_\-provisional\_\-diff\_\-profiles (char $\ast$ {\em doc}, char $\ast$ {\em pname}, {\bf PROFILE\_\-LIST} $\ast$$\ast$ {\em diffprofhandle})}\label{chain__provisional_8c_a47}


Find the array of provisional differenced brightness profiles. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em pname}]a string identifying the set of provisional measrements. \item[{\em diffprofhandle}]will get set to a pointer to the first profile list. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of valid profiles (should be 1 or 2). \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!find_provisional_earlywidths@{find\_\-provisional\_\-earlywidths}}
\index{find_provisional_earlywidths@{find\_\-provisional\_\-earlywidths}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int find\_\-provisional\_\-earlywidths (char $\ast$ {\em doc}, char $\ast$ {\em pname}, double $\ast$$\ast$ {\em earlywidthhandle})}\label{chain__provisional_8c_a48}


Find the array of provisional earlywood widths in the hash table. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em pname}]a string identifying the set of provisional measrements. \item[{\em earlywidthhandle}]will get set to a pointer to the first width. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of valid widths (should be 1 or 2). \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!find_provisional_latewidths@{find\_\-provisional\_\-latewidths}}
\index{find_provisional_latewidths@{find\_\-provisional\_\-latewidths}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int find\_\-provisional\_\-latewidths (char $\ast$ {\em doc}, char $\ast$ {\em pname}, double $\ast$$\ast$ {\em latewidthhandle})}\label{chain__provisional_8c_a49}


Find the array of provisional latewood widths in the hash table. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em pname}]a string identifying the set of provisional measrements. \item[{\em latewidthhandle}]will get set to a pointer to the first width. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of valid widths (should be 1 or 2). \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!find_provisional_profiles@{find\_\-provisional\_\-profiles}}
\index{find_provisional_profiles@{find\_\-provisional\_\-profiles}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int find\_\-provisional\_\-profiles (char $\ast$ {\em doc}, char $\ast$ {\em pname}, {\bf PROFILE\_\-LIST} $\ast$$\ast$ {\em profhandle})}\label{chain__provisional_8c_a46}


Find the array of provisional brightness profiles in the hash table. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em pname}]a string identifying the set of provisional measrements. \item[{\em profhandle}]will get set to a pointer to the first brightness list. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of valid profiles (should be 1 or 2). \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!find_provisional_widths@{find\_\-provisional\_\-widths}}
\index{find_provisional_widths@{find\_\-provisional\_\-widths}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int find\_\-provisional\_\-widths (char $\ast$ {\em doc}, char $\ast$ {\em pname}, double $\ast$$\ast$ {\em widthhandle})}\label{chain__provisional_8c_a45}


Find the array of provisional total ring widths in the hash table. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em pname}]a string identifying the set of provisional measrements. \item[{\em widthhandle}]will get set to a pointer to the first width. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of valid widths (should be 1 or 2). \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!get_provisional_full_chain@{get\_\-provisional\_\-full\_\-chain}}
\index{get_provisional_full_chain@{get\_\-provisional\_\-full\_\-chain}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}LIST\_\-NODE$\ast$ get\_\-provisional\_\-full\_\-chain (char $\ast$ {\em doc}, char $\ast$ {\em pname})}\label{chain__provisional_8c_a42}


Recover the full-resolution chain-coded boundary from the hash table. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em provbnum}]the number used to derive the hash key. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a pointer to the head of the boundary, or NULL on failure. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!get_provisional_insert_point@{get\_\-provisional\_\-insert\_\-point}}
\index{get_provisional_insert_point@{get\_\-provisional\_\-insert\_\-point}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int get\_\-provisional\_\-insert\_\-point (char $\ast$ {\em doc}, char $\ast$ {\em pname})}\label{chain__provisional_8c_a44}


Recover the insertion point in the list of chain-coded boundaries. 

The id number for the list item immediately before the insertion point should have been saved in the hash table, and may be the invalid id code if the insertion point is at the head of the list. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em pname}]a string identifying the set of provisional measrements. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the ring\_\-id number of a list item, or the invalid id on failure. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!get_provisional_small_chain@{get\_\-provisional\_\-small\_\-chain}}
\index{get_provisional_small_chain@{get\_\-provisional\_\-small\_\-chain}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}LIST\_\-NODE$\ast$ get\_\-provisional\_\-small\_\-chain (char $\ast$ {\em doc}, char $\ast$ {\em pname})}\label{chain__provisional_8c_a43}


Recover the downsampled chain-coded boundary from the hash table. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em pname}]a string identifying the set of provisional measrements. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a pointer to the head of the boundary, or NULL on failure. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!have_provisional_changes@{have\_\-provisional\_\-changes}}
\index{have_provisional_changes@{have\_\-provisional\_\-changes}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int have\_\-provisional\_\-changes (char $\ast$ {\em doc}, char $\ast$ {\em pname})}\label{chain__provisional_8c_a41}


Test if there are valid modified data in the provisional measurements. 

Even if there are no valid profiles, there will always be a (possibly empty) profile structure if there are valid widths, so use its presence as the test. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]the string identifying the document in the hash table. \item[{\em provbnum}]the number used to derive the hash key. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a boolena result, true if there are any valid measurements. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!make_chain@{make\_\-chain}}
\index{make_chain@{make\_\-chain}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}LIST\_\-NODE$\ast$ make\_\-chain (BOUNDER $\ast$ {\em bound})}\label{chain__provisional_8c_a23}


Generate a chain-coded boundary from a coordinate boundary representation. 

A BOUNDER structure represents boundaries by lists of points with explicit coordinates in continuous space, whereas chain-coded boundaries use lists of discrete relative steps instead. Conversion may reduce the total number of points, as the coordinates of several points may fall within the same discrete interval. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em bound}]points to the old BOUNDER boundary representation to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a newly-created chain-code boundary representation. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!provisional_check@{provisional\_\-check}}
\index{provisional_check@{provisional\_\-check}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int provisional\_\-check (double {\em x}, double {\em y}, LIST\_\-NODE $\ast$ {\em inner}, LIST\_\-NODE $\ast$ {\em outer})}\label{chain__provisional_8c_a40}


Check if a point lies between two chain-coded boundaries. 

We treat the boundaries as edges of a polygon, which is closed by defining an extra edge between the first points of the boundary pair, and another edge between the last points of the pair. For full background see Haines, Eric, \char`\"{}Point in Polygon Strategies\char`\"{}, Graphics Gems IV, ed. Paul Heckbert : Academic Press : 1994. p. 24--46. and equivalently: {\tt http://www.acm.org/tog/editors/erich/ptinpoly/} \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em x}]coordinate of the point to test; \item[{\em y}]coordinate of the point to test; \item[{\em inner}]points to the chaincoded representation of one boundary. \item[{\em outer}]points to the chaincoded representation of the other boundary. \end{description}
\end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!provisional_delete@{provisional\_\-delete}}
\index{provisional_delete@{provisional\_\-delete}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int provisional\_\-delete (char $\ast$ {\em doc}, int {\em provbnum}, {\bf IMAGE\_\-BYTE} $\ast$ {\em mimage}, MOSAIC\_\-INDEX $\ast$ {\em mindex}, LIST\_\-NODE $\ast$ {\em inner}, LIST\_\-NODE $\ast$ {\em deleted}, LIST\_\-NODE $\ast$ {\em outer}, LIST\_\-NODE $\ast$ {\em small})}\label{chain__provisional_8c_a36}


Delete an existing chain-coded boundary. 

Given a chain-coded boundary that is already in the chain map lists, and two enclosing boundaries (which are also already in the chain map, or are NULL), remove the boundary and re-compute the measurements to be associated with the enclosing boundaries (if they exist). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]a string identifying the hash table document. \item[{\em provbnum}]used to form the hash key to store the measurements. \item[{\em mimage}]points to the mosaic image. \item[{\em mindex}]points to the index to the mosaic image. \item[{\em inner}]points to the inner enclosing chain-coded boundary. \item[{\em delete}]points to the deleted existing chain-coded boundary. \item[{\em outer}]points to the outer enclosing chain-coded boundary. \item[{\em small}]points to the deleted low-resolution chain-coded boundary. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]an error code on failure, zero otherwise. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!provisional_extend@{provisional\_\-extend}}
\index{provisional_extend@{provisional\_\-extend}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int provisional\_\-extend (char $\ast$ {\em doc}, int {\em provbnum}, {\bf IMAGE\_\-BYTE} $\ast$ {\em mimage}, MOSAIC\_\-INDEX $\ast$ {\em mindex}, double {\em scale}, double {\em x}, double {\em y}, LIST\_\-NODE $\ast$ {\em initial}, LIST\_\-NODE $\ast$ {\em final})}\label{chain__provisional_8c_a38}


Extend the list of chain-coded boundaries by a new boundary at the end. 

Given the first and last chain-coded boundaries (which are already in the full-resolution chain map) and the coordinates of a point outside them, we construct a new boundary close to this point, derive revised measurements from the re-defined rings, and store them with the new boundaries in the hash table. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]a string identifying the hash table document. \item[{\em provbnum}]used to form the hash key to store the measurements. \item[{\em mimage}]points to the mosaic image. \item[{\em mindex}]points to the index to the mosaic image. \item[{\em scale}]the downsampling factor for the low-resolution chaincode. \item[{\em x}]the horizontal coordinate of the new boundary location. \item[{\em y}]the vertical coordinate of the new boundary location. \item[{\em initial}]points to the first existing chain-coded boundary. \item[{\em final}]points to the last existing chain-coded boundary. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]an error code on failure, zero otherwise. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!provisional_insert@{provisional\_\-insert}}
\index{provisional_insert@{provisional\_\-insert}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int provisional\_\-insert (char $\ast$ {\em doc}, int {\em provbnum}, {\bf IMAGE\_\-BYTE} $\ast$ {\em mimage}, MOSAIC\_\-INDEX $\ast$ {\em mindex}, double {\em scale}, double {\em x}, double {\em y}, LIST\_\-NODE $\ast$ {\em inner}, LIST\_\-NODE $\ast$ {\em outer})}\label{chain__provisional_8c_a35}


Insert a new boundary in the chain map between two existing boundaries. 

Given a pair of chain-coded boundaries (which are already in the full-resolution chain map) and the coordinates of a point between them, we construct a new boundary close to this point, derive revised measurements from the re-defined rings, and store them with the new boundaries in the hash table. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]a string identifying the hash table document. \item[{\em provbnum}]used to form the hash key to store the measurements. \item[{\em mimage}]points to the mosaic image. \item[{\em mindex}]points to the index to the mosaic image. \item[{\em scale}]the downsampling factor for the low-resolution chaincode. \item[{\em x}]the horizontal coordinate of the new boundary location. \item[{\em y}]the vertical coordinate of the new boundary location. \item[{\em inner}]points to the inner existing chain-coded boundary. \item[{\em outer}]points to the outer existing chain-coded boundary. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]an error code on failure, zero otherwise. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!provisional_missing@{provisional\_\-missing}}
\index{provisional_missing@{provisional\_\-missing}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int provisional\_\-missing (char $\ast$ {\em doc}, int {\em provbnum}, {\bf IMAGE\_\-BYTE} $\ast$ {\em mimage}, MOSAIC\_\-INDEX $\ast$ {\em mindex}, BOUNDBOX\_\-LIST {\em bbox}, LIST\_\-NODE $\ast$ {\em guide}, LIST\_\-NODE $\ast$ {\em small})}\label{chain__provisional_8c_a37}


Insert a missing ring after an existing chain-coded boundary. 

Given a chain-coded boundary that is already in the chain map lists, and two enclosing boundaries (which are also already in the chain map, or are NULL), copy the boundary and create a set of measurements to be associated with it and the original boundary as a special zero-width ring (the marker following a convention in other dendrochronology software for a ring whose position is inferred, but not visible in the part of the tree-ring sample used to produce a particular series of measurements). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em doc}]a string identifying the hash table document. \item[{\em provbnum}]used to form the hash key to store the measurements. \item[{\em mimage}]points to the mosaic image. \item[{\em mindex}]points to the index to the mosaic image. \item[{\em inner}]points to the inner enclosing chain-coded boundary. \item[{\em guide}]points to the existing chain-coded boundary to copy. \item[{\em outer}](unused) points to the outer enclosing chain-coded boundary. \item[{\em small}]points to the low-resolution chain-coded boundary to copy. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]an error code on failure, zero otherwise. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!provisional_point_distance@{provisional\_\-point\_\-distance}}
\index{provisional_point_distance@{provisional\_\-point\_\-distance}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}double provisional\_\-point\_\-distance (double {\em x}, double {\em y}, LIST\_\-NODE $\ast$ {\em boundary})}\label{chain__provisional_8c_a31}


Find the minimum distance between a point and a chain-coded boundary. 

Although the individual line segments making up the chain-coded boundary can only have two lengths, and are joined at nodes that lie on a regular grid, the coordinates of the point are not necessarily constrained in any way, so we treat it as the more general case of finding the distance between a point and an arbitrary polyline in continuous coordinates. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em x}]coordinate of the point whose distance we are determining. \item[{\em y}]coordinate of the point whose distance we are determining. \item[{\em x}]points to the chain-coded representation of a boundary. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the minimum point-boundary distance. \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!provisional_point_in_roi@{provisional\_\-point\_\-in\_\-roi}}
\index{provisional_point_in_roi@{provisional\_\-point\_\-in\_\-roi}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int provisional\_\-point\_\-in\_\-roi (MOSAIC\_\-INDEX $\ast$ {\em mindex}, double {\em x}, double {\em y})}\label{chain__provisional_8c_a29}


Test if coordinates fall within the region of interest in the image mosaic. 

Transform the coordinates to a frame with its origin an upper corner of the ROI and its x axis along the longest edge, then compare them to the lengths of the edges of the ROI. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em mindex}]points to the index to the mosaic image. \item[{\em x}]the horizontal coordinate of the new boundary location. \item[{\em y}]the vertical coordinate of the new boundary location. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]true if the coordinates are inside (the int is really a boolean). \end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!provisionalrings_destruct@{provisionalrings\_\-destruct}}
\index{provisionalrings_destruct@{provisionalrings\_\-destruct}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void provisionalrings\_\-destruct (void $\ast$ {\em data})}\label{chain__provisional_8c_a10}


Destroy a provisional measurement collection and all its sub-structures. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em data}]points to a {\bf Provisionalrings}{\rm (p.\,\pageref{structProvisionalrings})} structure to destroy. \end{description}
\end{Desc}
\index{chain_provisional.c@{chain\_\-provisional.c}!scale_boundary@{scale\_\-boundary}}
\index{scale_boundary@{scale\_\-boundary}!chain_provisional.c@{chain\_\-provisional.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void scale\_\-boundary (BOUNDER $\ast$ {\em bound}, double {\em scale})}\label{chain__provisional_8c_a11}


Scale the coordinate representation of a boundary by a scalar multiplier. 

Multiply all the x and y coordinates in the boundary representation, and remove the (now inavalid) index to the points. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em bound}]points to the BOUNDER encoded representation of the boundary. \item[{\em scale}]scale factor. \end{description}
\end{Desc}
