\rhead{Class SNAXEL}

\section{SNAXEL : The contour model unit} 

{\tt SNAXEL} is a class for calculating tangent and normal vectors, internal, external and total energies of a snaxel. A series of SNAXEL objects can form a complete contour. It is defined as below :

\begin{verbatim}
class SNAXEL {

    protected :
        double row, col ;       /* snaxel coordinate */
        double alpha, beta ;    /* shape coefficients */
        double lambda ;         /* local regularization parameters */
        double Eint, Eext ;     /* internal/external energy */
        double Esnaxel;         /* snaxel energy */
        SNAXEL *next;           /* next snaxel */
        SNAXEL *prev;           /* previous snaxel */
};
\end{verbatim}

Each SNAXEL object is internally connected with its two neighbouring snaxels so as to form a complete chain of contour. Besides, it consists of shape coefficients and local regularization parameter for the ease of energy calculation.

%
\subsection{Computing mean position}

\subsubsection*{Synopsis}
\begin{verbatim}
void meanPosition( SNAKEMODE mode, double cg_row,
                   double cg_col, SNAXEL *head, SNAXEL *tail, 
                   double *meanrow, double *meancol )	
\end{verbatim}

\subsubsection*{Arguments} 
\tb
	{\tt mode} & Snake mode of a contour - open or closed. \\
	{\tt cg\_row, cg\_col} & Coordinate of the centre of gravity of
			         a contour.\\
	{\tt avglen} & Average length of snaxels. \\ 
	{\tt head} & Pointer to the head of a contour. \\
	{\tt tail} & Pointer to the tail of a contour. \\	
	{\tt meanrow, meancol} &  Coordinate of the mean position.
\te

\subsubsection*{Description}
{\tt meanposition} calculates the mean position of snaxels and stores the coordinates in the locations pointed to by {\tt meanrow} and {\tt meancol}. The mean position can be referred to as the position of zero internal energy and calulated as following :
\eq
	\alpha_{i} u_{i_{\alpha}} + \beta_{i} u_{i_{\beta}}
\en
where $u_{i_{\alpha}}$ and $u_{i_{\beta}}$ are the neighbouring snaxels in the contour-centered coordinate formed. $\alpha_{i}$ and $\beta_{i}$ are the shape coefficients.


%
\subsection{Computing tangent vector}

\subsubsection*{Synopsis}
\begin{verbatim}
void    getDirectionVec( SNAKEMODE mode,
                         SNAXEL *head, SNAXEL *tail, 
                         double *Uv0_x, double *Uv0_y,
                         double *Uv1_x, double *Uv1_y)
\end{verbatim}

\subsubsection*{Arguments}
\tb		
	{\tt mode } & Snake mode of a contour - open or closed.  \\
	{\tt head} & Pointer to the head of a contour. \\
	{\tt tail} & Pointer to the tail of a contour. \\	
	{\tt Uv0\_x, Uv0\_y} & Unit vector of neighbouring snaxel (alpha).\\ 
	{\tt Uv1\_x, Uv1\_y} & Unit vector of neighbouring snaxel (beta).
\te

\subsubsection*{Description}
{\tt getDirectionVec} calculates two unit vectors $uv0=(uv0\_x, uv0\_y)$ and $uv1=(uv1\_x, uv1\_y)$, which can be used to compute the tangent vector. The tangent vector, ${\bf t}_{i}$, is given as follows :
\eq
	{\bf t}_{i} = \frac{u_{i} - u_{i-1}}{\|u_{i} - u_{i-1}\|} +
		\frac{u_{i+1} - u_{i}}{\|u_{i+1} - u_{i}\|}
\en
where $u$ is the snaxel in contour-centered coordinate formed, $\frac{u_{i} - u_{i-1}}{\|u_{i} - u_{i-1}\|}$ is $uv0$ and $\frac{u_{i+1} - u_{i}}{\|u_{i+1} - u_{i}\|}$ is $uv1$.

%	
\subsection{Computing normal vector}

\subsubsection*{Synopsis}
\begin{verbatim}
void    getNormalVec( SNAKEMODE mode,
                      SNAXEL *head, SNAXEL *tail,
                      double *nv_x, double *nv_y )
\end{verbatim}

\subsubsection*{Arguments}
\tb
	{\tt mode} & Snake mode of a contour - open or closed. \\ 
	{\tt head} & Pointer to the head of a contour. \\
	{\tt tail} & Pointer to the tail of a contour.\\
	{\tt nv\_x, nv\_y} & Coordinate of normal vector. \\
\te

\subsubsection*{Description}
{\tt getNormalVec} calculates the unit vector which is normal to the tangent vector of snaxel and stores the result in the locations pointed to by {\tt nv\_x} and {\tt nv\_y}.


%
\subsection{Calculating the {\tt SNAXEL} angle}

\subsubsection*{Synopsis}
\begin{verbatim}
	double	getNormalAng( SNAKEMODE mode, SNAXEL *head, SNAXEL *tail)
\end{verbatim}

\subsubsection*{Arguments}
\tb
	{\tt mode} & Snake mode of a contour - open or closed. \\ 
	{\tt head} & Pointer to the head of a contour. \\
	{\tt tail} & Pointer to the tail of a contour.	
\te

\subsubsection*{Returns}
Angle of snaxel in radians.

\subsubsection*{Description}
{\tt getNormalAng} computes the angle which is normal to the tangent vector of a snaxel.


%
\subsection{Showing snaxel}

\subsubsection*{Synopsis}
\begin{verbatim}
void show( IMAGE *img, short Old_Row, short Old_Col, 
           int pt_Xoffset = 0, int pt_Yoffset = 0 ) 
\end{verbatim}

\subsubsection*{Arguments}
\tb
	{\tt *img} & Background image on which the SNAKEL is to be shown. \\
	{\tt Old\_Col, Old\_Row} & Coordinate of a snaxel before deformation. \\
	{\tt pt\_Xoffset, pt\_Yoffset} & Offset position of a snaxel. \\
\te

\subsubsection*{Description}
{\tt show} displays a snaxel on top of the background image. This is done by resetting the dot at [{\tt Old\_col, Old\_Row}] to the background image data, and then placing a dot at the current snaxel position. The offset position need to be specified if the background image occupies only certain portion of an X window. The user should ensure that the background image have been displayed before calling {\tt show}.

%
\subsection{Interface row and column information}

\subsubsection*{Synopsis}
\begin{verbatim}
	double getRow(void) 
	double getCol(void)
	void putRow(double _row)
	void putCol(double _col) 
\end{verbatim}

\subsubsection*{Returns}
Snaxel coordinate.

\subsubsection*{Description}
These methods facilitate the retrieval and accessing of snaxel co-ordinate.


%
\subsection{Interface snaxel energy information}

\subsubsection*{Synopsis}
\begin{verbatim}
	double  getEint(void)
	double  getEext(void)
	double  getEsnaxel(void)
	void  putEsnaxel( double _Esnaxel )
	void  putEint( double _Eint )
	void  putEext( double _Eext ) 
\end{verbatim}

\subsubsection*{Returns}
Internal, external or total snaxel energy.

\subsubsection*{Description}
These methods facilitate the retrieval and accessing of snaxel energy information.


%
\subsection{Interface parameter information}

\subsubsection*{Synopsis}
\begin{verbatim}
	double  getAlpha(void)
	double  getBeta(void) 
	double  getLambda(void)
	void  putAlpha( double _alpha )
	void  putBeta( double _beta )
	void  putLambda( double _lambda )
\end{verbatim}

\subsubsection*{Returns}
Alpha ($\alpha$), beta ($\beta$) or lambda ($\lambda$).

\subsubsection*{Description}
These methods facilitate the retrieval and accessing of snaxel parameters.


%
\subsection{Interface pointers to neighbouring snaxels}

\subsubsection*{Synopsis}
\begin{verbatim}		
	SNAXEL	*getNext(void) 
	SNAXEL	*getPrev(void) 
	SNAXEL	*getNext(SNAKEMODE mode, SNAXEL *head)
	SNAXEL	*getPrev(SNAKEMODE mode, SNAXEL *tail)
	void  putPrev( SNAXEL *_prev ) 
	void  putNext( SNAXEL *_next )	 

\end{verbatim}

\subsubsection*{Arguments}
\tb
	{\tt mode} & Snake mode of a contour - opened or closed. \\
	{\tt head} & Pointer to the head of a contour. \\
	{\tt tail} & Pointer to the tail of a contour.\\
	{\tt \_prev} & Pointer to the previous snaxel. \\
	{\tt \_next} & Pointer to the next snaxel.
\te

\subsubsection*{Returns}
Pointer to previous or next snaxel.

\subsubsection*{Description}
These methods facilitate the retrieval and accessing of the neighbouring snaxels. If snake mode is specified, the following will be done :

\begin{enumerate}
	\item For an open snake
	\begin{itemize}
		\item {\tt getPrev} retrieves or accesses the previous snaxel if
			it is not the head of a contour. Otherwise, the third
			snaxel will be retrieved or accessed.
		\item {\tt getNext} retrieves or accesses the next snaxel if it 
			is not the tail of a contour. Otherwise, the snaxel
			retrieved or accessed is that of two snaxels before.
	\end{itemize}
	
	\item for a closed snake
	\begin{itemize}
		\item {\tt getPrev} retrieves or accesses the previous snaxel if
			it is not the head of a contour. Otherwise, the tail of
			a contour will be retrieved or accessed.
		\item {\tt getNext} retrieves or accessed the next snaxel if it
			is not the tail of a contour. Otherwise, the head of a
			contour will be retrieve or accessed.
	\end{itemize}
\end{enumerate}
	

%
\subsection{Example : Using mean position to calculate Internal energy}
		
This example demonstrates how the internal energy of a snaxel is calculated. The internal energy measures the deviation of a snaxel from its mean position after deformation.

\begin{verbatim}
void testmain( char *confile,   /* standard contour file */
               int mag )        /* magnification factor */
{
        SNAXEL *sptr;           /* SNAXEL object */
        CONTOUR mycontour;      /* CONTOUR object */
        double l_inf;           /* infinity norm */
        double meanrow,         /* mean position of snaxel */
               meancol;
        double avglen;          /* average length of snaxel */
        double Eint;            /* Internal energy */
        double cg_row,          /* center of gravity (CG) */
               cg_col;
        register short i;

        /* Read and show the contour */
        if ( mycontour.read( confile ) )        exit( -1 );

        mycontour.display(mag);

        /* Compute the average distance between snaxels and CG*/
        mycontour.computeCG();
        avglen = mycontour.computeAvgLength();
        cg_row = mycontour.getCgRow();
        cg_col = mycontour.getCgCol();
        printf("\nCentre of gravity at row %d col %d\n",
                                ROUNDOFF( cg_row ), ROUNDOFF( cg_col ));

        mycontour.imageCentered();

        /* Calculating the internal energy for each snaxel */
        for (i=0, sptr=mycontour.getHead(); sptr; sptr=sptr->getNext(),i++) {
                if ( fabs(sptr->getAlpha() ) < VERY_SMALL &&
                        fabs(sptr->getBeta() )  < VERY_SMALL )
                        Eint = 1.0;

                /* compute shape coeff. (alpha & beta) with infinity norm */
                sptr->meanPosition( mycontour.getMode(), cg_row, cg_col,
                                  mycontour.getHead(), mycontour.getTail(),
                                  &meanrow, &meancol);
                l_inf = MAX( fabs( meanrow - sptr->getRow() ),
                             fabs( meancol - sptr->getCol() ) );
                Eint =  SQR( l_inf / avglen );
                printf("\nSnaxel %d energy = %f",i,Eint);
        }

        printf("\nEnd of test.");
        printf("\nPress enter to continue.");
        getchar();
        xwin_close();
}
\end{verbatim}

{\tt meanPosition} measure the mean position of current snaxel, while infinity norm measures the deviation of a snaxel.

%
\subsection{Example : Verifying vector calculations}
 
\begin{verbatim}
void testmain( char *confile,   /* standard contour file */
               int mag )        /* magnification factor */
{
        SNAXEL *sptr;           /* SNAXEL object */
        CONTOUR mycontour;      /* CONTOUR object */
        double uv_x, uv_y,      /* tangent vector */
               uv0_x, uv0_y,
               uv1_x, uv1_y;
        double nv_x, nv_y;      /* normal vector */
        double Amodel,          /* tangent angle */
               Anorm;           /* normal angle */
        register short i;

        /* Read and show the contour */
        if ( mycontour.read( confile ) ) exit(-1);

        /* Compute the average distance between snaxels and CG*/
        mycontour.computeCG();
        mycontour.imageCentered();

        /* Calculating the internal energy for each snaxel */
        for (i=0, sptr=mycontour.getHead(); sptr;sptr=sptr->getNext(), i++) {

                sptr->getDirectionVec(mycontour.getMode(),
                                      mycontour.getHead(),
                                      mycontour.getTail(),
                                      &uv0_x,&uv0_y,&uv1_x,&uv1_y);

                /* tangent vector at current snaxel */
                uv_x = uv0_x + uv1_x;
                uv_y = uv0_y + uv1_y;

                Amodel = ATAN2( uv_x, uv_y );

                sptr->getNormalVec(mycontour.getMode(),mycontour.getHead(),
                                   mycontour.getTail(),&nv_x,&nv_y);
                Anorm = ATAN2(nv_x,nv_y);

                /* for verification, angle should be 90 degree apart */
                printf("\nAngle : %3.6f\t Normal : %3.6f",
                          ANGLE(Amodel), ANGLE(Anorm));
        }

        mycontour.display(mag);
        printf("Press enter to continue ");
        getchar();
        printf("\nEnd of test.\n\n");
        xwin_close();
}

\end{verbatim} 	 
		 
This program calculates the tangent and normal angle of each snaxel. {\tt getDirectionVec} calculates the tangent vector at each snaxel, while {\tt getNormalVec} rotates the tangent direction by 90 degree so as to compute the normal vector.