pfs.h

Go to the documentation of this file.

/*
** ---------------------------------------------------------------
**
** @name Parametrized Faceted Surface module
**
** ---------------------------------------------------------------
**
** @date    31-Aug-2006
** @author  Luiz F. Martha
** @version 1.0
**
** ---------------------------------------------------------------
** pfs.h  -  Parametrized Faceted Surface module API.
**
** ---------------------------------------------------------------
** Description:
**
** This header file contains declarations of exported functions
** and global definitions of the parametric facet surface module.
**
** This module contains functions to represent a typical faceted 
** (triangulated) surface mesh data and functions to create a 
** two-dimensional parametric space associated to the faceted 
** surface.
** Basically, a pair of surface parametric values are associated 
** to each node in the mesh.  This is mainly based on the wrk
** of Levy, Petitjean, Ray, and Maillot, "Least squares conformal
** maps for automatic texture atlas generation," SIGRAPH 
** proceedings, 2002
** The local data structure consists of a node (vertex) vector
** with nodal coordinates and node-node adjacency relationships,
** and an element (face) vector with nodal connectivity.
**
** ---------------------------------------------------------------
** Initialization of nodal parametric coordinates:
**
** The initial parametric coordinates are obtained from the 
** projection of the nodal points onto a reference plane.
** This plane contains the reference element, which is the
** the element that has the normal vector closest to the 
** global average surface normal vector.
** The global average normal vector is obtained from the average
** of the normal vectors of all elements of the surface.  This is
** a weighted average considering the area as the weight of each
** element.
** The reference element containts the origin of the parametric 
** space.  The origin is the first node of the element, which is
** called the reference node.  The parametric coordinates of the
** reference node are (u,v) = (0,0), which will never change 
** during the iterative solution described below.
** The algorithm tries to lay the first plane parametric vector 
** be at the projection of the major x-axis with the plane.  
** If the x-axis is almost (less then 30 degrees) parallel to the 
** plane normal vector, it tries to do the same with the y-axis and 
** z-axis (in this order).
**
** ---------------------------------------------------------------
** Iterative solution for nodal parametric coordinates:
**
** The solution of nodal parametric values is performed by means
** of an iterative procedure, which consists of several passes 
** along the nodes of the surface.  In each iteration of a pass,
** a local solution of the conformal mapping problem is performed 
** at a node.  A 2 by 2 system of equations is assembled in which 
** the equation coefficients correspond to the conformal map 
** coefficients of the node and the forcing vector is obtained
** from the current parametric values and coefficients of all the
** adjacent nodes.  The solution of the system of equation furnishes
** the new parametric values of a node in each iteration.  The
** iterative solution terminates when all changes in parametric
** values of one pass in relation to the previous pass are small 
** (within a tolerance).  The tolerance used to terminate the 
** iterative solution is defined as a factor of the size of first 
** reference element side (from the reference node to the next 
** element node in counter-clockwise order).
** In each pass, the iterative solution follows an order that 
** traverses the nodes by levels of adjacency.  The first level 
** contains the reference node.  Each level is created with the 
** nodes that are adjacent to the nodes of the previous level 
** that have not been used by any level.
**
** ---------------------------------------------------------------
** Normalization of nodal parametric coordinates:
**
** After the iterative solution, the nodal parametric coordinates
** are normalized in such a way that the minimum parametric value
** is zero and the maximum is one.  In the normalization, the same
** scaling factor is applyed to both u and v parametric coordinates
**
** ----------------------------------------------------------------
**
** Created:    17-Jan-2005    Luiz F. Martha
**    Stolen from old pfs module based on the work of
**    Michael Floater: "Parametrization and smooth approximation 
**    of surface triangulation", Computer Aided Geometric Design, 
**    vol. 14, pp. 231-250, 1997.
**
** Modified:   17-Feb-2006    Alexandre A. Del Savio
**    Created the function pfsProjectOn. 
**    This function was based on nSurfacePFS package, by 
**    William Lira and Antonio Miranda.
**
** Modified:   20-Feb-2006    Alexandre A. Del Savio
**    Created the function pfsGetJacobian.
**    This function was based on nSurfacePFS package, by 
**    William Lira and Antonio Miranda.
**
** Modified:   22-Feb-2006    Alexandre A. Del Savio
**    Modified the function pfsGetJacobian. It passed to
**    return the components of the normal vector of 
**    element face where is the point.
**
** Modified:   22-Feb-2006    William W. M. Lira
**    Created the function pfsEval.
**    This function was based on nSurfacePFS package, by 
**    William Lira and Antonio Miranda.
**
** Modified:   23-Feb-2006    Alexandre A. Del Savio
**    Modified the function pfsAddElem. It passed to have
**    a return. If there is no active surface it returns a
**    false (0) status, otherwise it returns a true (1) 
**    status.
**
** Modified:   20-Apr-2006    Alexandre A. Del Savio
**    Modified the global functions name from pfs to pfsR 
**    due names conflicts with nurbs_pfs.lib of Recon3D.
**
** Modified:   30-Jul-2006    Luiz F. Martha
**    Created exported functions pfsItrNumLoops, pfsItrFirstLoopNode,
**    pfsItrNextLoopNode.
**
** Modified:   31-Aug-2006    Luiz F. Martha
**    Created exported functions pfsCompleteParSpace, pfsSetCurrElem ...
**
** Modified:   09-July-2007    Gisele Cunha Holtz
**    Criada as variáveis pfs_iter e pfs_node, apenas por questões
**    de facilitar a identificação da iteração e do nó quando
**    ocorre um problema.
**    
**/

#ifndef _PFS_H
#define _PFS_H


#ifdef __cplusplus
extern "C" {
#endif

/*
** ---------------------------------------------------------------
** Global definitions:
*/
#define PFS_SUCCESS 1
#define PFS_ITERATION_END 0
#define PFS_NO_SURFACE_DEFINED -1
#define PFS_NON_MANIFOLD_EDGE -2
#define PFS_INVERSE_INCIDENCE -3
#define PFS_NON_MANIFOLD_VERTEX -4

int pfs_iter;
int pfs_node;

/*
** ---------------------------------------------------------------
** Exported function:
*/

void *pfsRInitSurf( int maxnodes, int maxelems );

void pfsRActivateSurf( void *surf );

void pfsRFreeSurf( void *surf );

int  pfsRAddNode( double x, double y, double z );

int pfsRAddElem( int v0, int v1, int v2 );

int  pfsRCompleteSurf( void );

void pfsRSolveSurfPar( int maxnumiter );

void pfsCompleteParSpace( void );

int  pfsRItr3dBoundBox( double *xmin, double *xmax, 
                       double *ymin, double *ymax,
                       double *zmin, double *zmax );

int  pfsRItrParBoundBox( double *umin, double *umax, 
                        double *vmin, double *vmax );

int  pfsRItrFirstElem( void );

int  pfsRItrNextElem( void );

int  pfsRItrFirst3dElem( double xmin, double xmax, 
                        double ymin, double ymax, 
                        double zmin, double zmax );

int  pfsRItrNext3dElem( double xmin, double xmax, 
                       double ymin, double ymax, 
                       double zmin, double zmax );

int  pfsRItrFirstParElem( double umin, double umax, 
                         double vmin, double vmax );

int  pfsRItrNextParElem( double umin, double umax, 
                        double vmin, double vmax );

void pfsRSetCurrElem( void *elem );

int  pfsRGetElem( double x, double y, double z, void **elem );

int pfsRGetLoopElem( double x, double y, double z, void **elem );

int  pfsRItrElemNode( int *id );

void pfsRItrElemCenter( double *x, double *y, double *z );

void pfsRItrElemNormal( double *nx, double *ny, double *nz );

void pfsRItrElem3dBox( double *xmin, double *ymin, double *zmin,
                      double *xmax, double *ymax, double *zmax );

void pfsRItrElemParBox( double *umin, double *vmin,
                       double *umax, double *vmax );

int  pfsRItrNumNodes( void );

void pfsRItrNodeCoords( int id, double *x, double *y, double *z );

void pfsRItrNodeNormal( int id, double *nx, double *ny, double *nz );

void pfsRItrNodeJacobian( int id, 
                         double *xdu, double *ydu, double *zdu,
                         double *xdv, double *ydv, double *zdv );

void pfsRItrNodeParVals( int id, double *u, double *v );

int  pfsRItrNumLoops( void );

int  pfsRItrFirstLoopNode( int loop_id, int *id );

int  pfsRItrNextLoopNode( int loop_id, int ref_id, int *id );

int pfsRProjectOn( double x, double y, double z,
                  double *u, double *v );

int pfsRGetJacobian( double u, double v, 
                    double *xdu, double *ydu, double *zdu,
                    double *xdv, double *ydv, double *zdv,  
                    double *xdw, double *ydw, double *zdw );

int pfsREval( double u, double v, double *x, double *y, double *z );

int pfsRShot( void *init_elem, double x0, double y0, double z0,
             double u_shot, double v_shot, double len,
             void **end_elem, double *x1, double *y1, double *z1 );
#ifdef __cplusplus
}
#endif

#endif

---