mi32/transgen.h

Go to the documentation of this file.

/**
 * \file transgen.h <mi32/transgen.h>
 * \brief Function prototypes and macros for TransGen functions
 *
 * \if NODOC
 * $Id: transgen.h_v 1.45 2003/09/15 13:49:56 fileserver!dwilliss Exp $
 *
 * $Log: transgen.h_v $
 * Revision 1.45  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.44  2003/06/12 19:32:04  scowan
 * More const.
 *
 * Revision 1.43  2003/03/14 18:25:51  mju
 * Add SetMaxInsertVertices.
 *
 * Revision 1.42  2002/08/19 15:32:40  scowan
 * Fixed g++ 3.1 warning.
 *
 * Revision 1.41  2000/10/26 21:53:24  mju
 * Add default ctor for TRANSPARM.
 *
 * Revision 1.40  2000/10/26 21:46:48  mju
 * Disallow copy ctor / assignment for TRANSPARM.
 *
 * Revision 1.39  2000/09/05 13:14:45  mju
 * Fix default parm for TransGenIsFlipped().
 *
 * Revision 1.38  2000/09/01 20:18:19  msmith
 * Genitor documentation
 *
 * Revision 1.37  2000/08/03 13:44:39  mju
 * Use inlines instead of macros so will be documented by Genitor.
 *
 * Revision 1.36  1999/12/29 17:12:52  mju
 * Add TransGenIsFlipped().
 *
 * Revision 1.35  1999/05/19 17:19:03  mju
 * Add TransgenCopy().
 *
 * Revision 1.34  1999/05/07  21:25:37  mju
 * Hdr restruct.
 *
 * Revision 1.33  1999/04/29  22:07:57  mju
 * Move TRANSFUNC here.
 * Move Disect funcs here needing TRANSFUNC/TRANSPARM.
 *
 * Revision 1.32  1999/04/29  16:02:24  mju
 * Move TRANSPARM structure here.
 *
 * Revision 1.31  1999/04/28  17:41:38  mju
 * Include ctrlpt.h.
 *
 * Revision 1.30  1999/04/27  16:01:00  mju
 * Use "const" for more functions.
 *
 * Revision 1.29  1999/03/25  22:08:12  mju
 * Add GetInput/OutputModel.
 *
 * Revision 1.28  1999/03/17  15:42:32  mju
 * Use const for more "set" functions.
 *
 * Revision 1.27  1999/03/15  15:37:12  mju
 * Use const for Coord2DT funcs and FindBest funcs.
 *
 * Revision 1.26  1999/01/05  19:12:37  scowan
 * Swapped multiple keywords
 *
 * Revision 1.25  1998/10/26 18:26:37  mju
 * Add functions to set max error for point insertion.
 * Make SetDoInsert() a function instead of a macro.
 *
 * Revision 1.24  1998/08/28  16:43:49  scowan
 * geom dll update.
 *
 * Revision 1.23  1998/06/17  17:16:15  mju
 * Add GetInput/OutputProj().
 *
 * Revision 1.22  1997/10/22  16:31:32  mju
 * Add TransGenConvPointSet().
 *
 * Revision 1.21  1997/03/05  14:05:31  mju
 * Add TransGenGetInput/OutputTransAffine.
 *
 * Revision 1.20  1996/12/31  21:35:33  mju
 * Add TransGenSetAffineApprox().
 *
 * Revision 1.19  1996/12/20  16:37:34  coffee!dwilliss
 * Added __cplusplus things
 *
 * Revision 1.18  1996/10/01  16:20:59  scowan
 * Added TransGenIsInitialized.
 *
 * Revision 1.17  1996/08/21  00:29:32  mju
 * Change IsReversibleAll to IsReversible.
 *
 * Revision 1.16  1996/08/12  17:04:29  mju
 * Add TransGenConvPointMapToMap...
 *
 * Revision 1.15  1996/06/18  21:42:54  mju
 * Add prototype for TransGenSetExtrapOutside().
 *
 * Revision 1.14  1996/05/24  23:19:53  mju
 * Add TransGetGetAffineLocal() prototype.
 *
 * Revision 1.13  1996/05/21  16:27:18  mju
 * Add TRANSGENCOORD definitions.
 * Add TransGenGetPiece prototypes.
 *
 * Revision 1.12  1996/05/17  21:14:51  mju
 * Remove prototype for TransGenAllocPoints() as no longer available.
 *
 * Revision 1.11  1996/05/17  00:07:52  mju
 * Change some prototypes to "int" from "void".
 *
 * Revision 1.10  1996/05/16  00:20:10  mju
 * Add more prototypes.
 *
 * Revision 1.9  1996/05/15  19:48:50  mju
 * Add prototypes for TransGenTransFuncFwd/Inv.
 *
 * Revision 1.8  1996/05/14  21:21:24  mju
 * Add macros and function prototypes.
 *
 * Revision 1.7  1996/05/14  16:46:47  mju
 * Change API for TransGenSetXxxxTransCtrlPoint().
 *
 * Revision 1.6  1996/05/10  23:04:07  mju
 * Add TransGenCopyInputToOutput and CopyOutputToInput.
 *
 * Revision 1.5  1996/05/09  17:14:20  mju
 * Add additional function prototypes.
 *
 * Revision 1.4  1996/05/02  23:50:04  mju
 * Add TransGenSetupObjProjTrans().
 *
 * Revision 1.3  1996/05/02  16:44:12  mju
 * Add additional function prototypes.
 *
 * Revision 1.2  1995/04/14  21:16:31  mju
 * Fix prototypes for TransGenSet...ProjHandle.
 *
 * Revision 1.1  1995/04/14  17:03:14  mju
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_MI32_TRANSGEN_H
#define  INC_MI32_TRANSGEN_H

#ifndef  INC_MI32_STDDEFNS_H
#include <mi32/stddefns.h>
#endif
#ifndef INC_MI32_CTRLPT_H
#include <mi32/ctrlpt.h>
#endif

#ifdef GEOMDLL
   #define GEOMLIBEXPORT MI_DLLEXPORT
#else
   #define GEOMLIBEXPORT MI_DLLIMPORT
#endif

struct MAPPROJPARM;

/* Prototype for generic transformation function */
typedef int (*TRANSFUNC)(void*,void*,int,int,void*);

/*----------------------------------------------------------------------------*/
/*    TRANSPARM - Transformation parameters used by TransGen...() functions   */
/*----------------------------------------------------------------------------*/

struct TRANSPARM {
   // MEMBERS
   unsigned InitDone:1,          //!<  Set if has been initialized 
            IsAffineAll:1,       //!<  Set if entire transformation is affine, overrides all other flags 
            IsIdentityAll:1,     //!<  Set if entire transformation is identity 
            SameProj:1,          //!<  Set if input and output projections are the same (or either undefined) 
            IsReversible:1,      //!<  Set if transformation is reversible 
            DoGeneric:1,         //!<  Set if just do generic transformation 
            PrimaryDirInverse:1, //!<  Set if primary transformation direction is "inverse" 
            DoInsertPoints:1,    //!<  Set if should "insert" points in TransGenConvPoints...() 
            sparebits:24;
   Mat3x3 ItoO;            //!<  Input to Output transformation if IsAffineAll set 
   Mat3x3 OtoI;            //!<  Output to Input transformation if IsAffineAll set 
   TRANSFUNC GenTransFwd;  //!<  Generic transformation used if DoGeneric is set 
   TRANSFUNC GenTransInv;  //!<  Generic transformation used if DoGeneric is set 
   void *GenTransData;     //!<  Data for generic transformation function 
   void *internal;         //!<  Private data internal to TransGen toolkit 
   /* DO NOT CHANGE SIZE OF THIS STRUCTURE UNDER PENALTY OF ILLOP'S */

   //! Default constructor, performs no initialization.
   TRANSPARM (
      ) {
      }
private:
   #ifndef GENERATING_DOXYGEN_OUTPUT

   //! UNSUPPORTED / UNIMPLEMENTED
   TRANSPARM (const TRANSPARM&);             //! Copy ctor
   TRANSPARM& operator= (const TRANSPARM&);  //! Assignment
   #endif // GENERATING_DOXYGEN_OUTPUT
   };

#define  TRANSDIR_Forward  0
#define  TRANSDIR_Inverse  1


#define  TRANSGENCOORD_Input     0x00000001
#define  TRANSGENCOORD_Output    0x00000002
#define  TRANSGENCOORD_External  0x00000004
#define  TRANSGENCOORD_Map       0x00000008


#if defined(__cplusplus)
extern "C" {
#endif

//! Disect a transformation into component parts (scale, rotation, shear).
//!
//! #include <mi32/geom2d.h>
//! This function is used to compute the affine transformation parameters above at a given point for
//! a general transformation function.
GEOMLIBEXPORT int DisectGen2D (
   const DPOINT2D *point,              //!< Point to compute values at
   double size,                        //!< Size in source coodinates over which to compute (usually 1.0)
   double *xscale,                     //!< X scale at specified point returned
   double *yscale,                     //!< Y scale at specified point returned
   double *rotangle,                   //!< Rotation angle at specified point returned (radians)
   double *shearangle,                 //!< Shear angle at specified point returned (radians)
   TRANSFUNC transfunc,                //!< Transformation function to "disect"
   void *transfuncdata                 //!< "userdata' for transfunc
   );

//! Transform single point from "input" to "output" coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointFwd (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *ipoint,             //!< Input point
   DPOINT2D *opoint                    //!< Converted point coordinates returned
   );

//! Transform single point from "output" to "input" coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointInv (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *ipoint,             //!< Input point
   DPOINT2D *opoint                    //!< Converted point coordinates returned
   );

//! Transform single point from "input" to map coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointInputToMap (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *ipoint,             //!< Input point
   DPOINT2D *opoint                    //!< Converted point coordinates returned
   );

//! Transform single point from map to "input" coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointMapToInput (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *ipoint,             //!< Input point
   DPOINT2D *opoint                    //!< Converted point coordinates returned
   );

//! Transform single point from input map coordinates to output map coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointMapToMapFwd (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *ipoint,             //!< Input point
   DPOINT2D *opoint                    //!< Converted point coordinates returned
   );

//! Transform single point from output map coordinates to input map coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointMapToMapInv (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *ipoint,             //!< Input point
   DPOINT2D *opoint                    //!< Converted point coordinates returned
   );

//! Transform single point from map to "output" coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointMapToOutput (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *ipoint,             //!< Input point
   DPOINT2D *opoint                    //!< Converted point coordinates returned
   );

//! Transform single point from "output" to map coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointOutputToMap (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *ipoint,             //!< Input point
   DPOINT2D *opoint                    //!< Converted point coordinates returned
   );

//! Transform N-dimensional point "set" from "input" to "output" coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointSetFwd (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const double *ipoint,               //!< Input point array
   INT32 iNumPoints,                   //!< Number of input points
   int NumDim,                         //!< Number of dimensions in point array (usually 2 or 3)
   double *opoint                      //!< Output point array
   );

//! Transform N-dimensional point "set" from "output" to "input" coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvPointSetInv (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const double *ipoint,               //!< Input point array
   INT32 iNumPoints,                   //!< Number of input points
   int NumDim,                         //!< Number of dimensions in point array (usually 2 or 3)
   double *opoint                      //!< Output point array
   );

//! Transform N-dimensional point array from "input" to "output" coordinates.
//!
//! @return Error code < 0
//! This function returns a pointer to an internally allocated array.  Do not free this pointer.
//! The internal array may be freed via TransGenFreeParm() or TransGenFreePoints().
//! Note: The number of output points may be different than iNumPoints, if you want to transform the
//! points one-to-one use TransGenConvPointSetFwd().
GEOMLIBEXPORT int TransGenConvPointsFwd (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const double *ipoint,               //!< Input point array
   INT32 iNumPoints,                   //!< Number of input points
   int NumDim,                         //!< Number of dimensions in point array (usually 2 or 3)
   double **opoint,                    //!< Output point array (pointer returned, DO NOT FREE)
   INT32*                              //! Number of output points returned
   );

//! Transform N-dimensional point array from "output" to "input" coordinates.
//!
//! @return Error code < 0
//! This function returns a pointer to an internally allocated array.  Do not free this pointer.
//! The internal array may be freed via TransGenFreeParm() or TransGenFreePoints().
//! Note: The number of output points may be different than iNumPoints, if you want to transform the
//! points one-to-one use TransGenConvPointSetInv().
GEOMLIBEXPORT int TransGenConvPointsInv (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const double *ipoint,               //!< Input point array
   INT32 iNumPoints,                   //!< Number of input points
   int NumDim,                         //!< Number of dimensions in point array (usually 2 or 3)
   double **opoint,                    //!< Output point array (pointer returned, DO NOT FREE)
   INT32*                              //! Number of output points returned
   );

//! Transform rectangle (DRECT2D) from "input" to "output" coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvRectFwd (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DRECT2D *irect,               //!< Input rectangle to be translated
   DRECT2D *orect,                     //!< Output rectangle
   int sidepoints                      //!< Number of points per side of box if needed (0 for default)
   );

//! Transform rectangle (DRECT2D) from "output" to "input" coordinates.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenConvRectInv (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DRECT2D *irect,               //!< Input rectangle to be translated
   DRECT2D *orect,                     //!< Output rectangle
   int sidepoints                      //!< Number of points per side of box if needed (0 for default)
   );

//! Copy one TRANSPARM to another
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenCopy (
   TRANSPARM *otp,                     //!< Output transformation parameter structure
   const TRANSPARM *itp                //!< Input transformation parameter structure
   );

//! Copy "input parameters" from on TRANSPARM structure to another.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenCopyInputParms (
   TRANSPARM *dtransparm,              //!< Destination transformation parameters
   const TRANSPARM *stransparm         //!< Source transformation parameters
   );

//! Copy "input parameters" from one TRANSPARM to "output parameters" of another.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenCopyInputToOutput (
   TRANSPARM *dtransparm,              //!< Destination transformation parameters
   const TRANSPARM *stransparm         //!< Source transformation parameters
   );

//! Copy "output parameters" from one TRANSPARM to another.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenCopyOutputParms (
   TRANSPARM *dtransparm,              //!< Destination transformation parameters
   const TRANSPARM *stransparm         //!< Source transformation parameters
   );

//! Copy "output parameters" from one TRANSPARM to "input parameters" of another.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenCopyOutputToInput (
   TRANSPARM *dtransparm,              //!< Destination transformation parameters
   const TRANSPARM *stransparm         //!< Source transformation parameters
   );

//! Determine scale/rotation/shear at specified point for forward transformation.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenDisectFwd (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *point,              //!< Reference point at which values will be computed (NULL for 0,0)
   double size,                        //!< Size of area over which to compute values
   double *xscale,                     //!< X scale factor returned (NULL if don't need)
   double *yscale,                     //!< Y scale factor returned (NULL if don't need)
   double *rotangle,                   //!< Rotation angle returned in radians (NULL if don't need)
   double *shearangle                  //!< Shear angle returned in radians (NULL if don't need)
   );

//! Determine scale/rotation/shear at specified point for inverse transformation.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenDisectInv (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *point,              //!< Reference point at which values will be computed (NULL for 0,0)
   double size,                        //!< Size of area over which to compute values
   double *xscale,                     //!< X scale factor returned (NULL if don't need)
   double *yscale,                     //!< Y scale factor returned (NULL if don't need)
   double *rotangle,                   //!< Rotation angle returned in radians (NULL if don't need)
   double *shearangle                  //!< Shear angle returned in radians (NULL if don't need)
   );

//! Free all allocated entried in the TRANSPARM structure.
//!
//! @return nothing
GEOMLIBEXPORT void TransGenFreeParm (
   TRANSPARM *transparm                //!< Transformation parameter structure
   );

//! Free output point array in the TRANSPARM structure.
//!
//! @return nothing
GEOMLIBEXPORT void TransGenFreePoints (
   TRANSPARM *transparm                //!< Transformation parameter structure
   );

//! Get affine (Mat3x3) transformation if available.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenGetAffine (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   MAT3X3 ItoO,                        //!< Input to output transformation returned (NULL if don't need)
   MAT3X3 OtoI                         //!< Output to input transformation returned (NULL if don't need)
   );

//! Determine affine transformation at specified point.
//!
//! return Error code < 0
//! The flags value determines if the specified point is in "input" or "output" coordinates.
GEOMLIBEXPORT int TransGenGetAffineLocal (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   const DPOINT2D *point,              //!< Reference point at which values will be computed
   double size,                        //!< Size of area over which to compute values
   MAT3X3 ItoO,                        //!< Input to output transformation returned
   MAT3X3 OtoI,                        //!< Output to input transformation returned
   UINT32 flags                        //!< TRANSGENCOORD_Input or TRANSGENCOORD_Output
   );

//! Get input transformation model.
//!
//! @return Transformation model
GEOMLIBEXPORT UINT16 TransGenGetInputModel (
   const TRANSPARM *tp                 //!< Transformation parameter structure
   );

//! Get "input projection parameters" from TRANSPARM.
//!
//! @return See below
//! If a non-NULL value is passed for "projparm" then a pointer to this structure will be
//! returned.  If NULL is passed for "projparm" then either NULL or a pointer to an internal
//! projection parameter structure will be returned depending on whether a projection has
//! previously been specified via TransGenSetInputProj() or TransGenSetInputProjHandle().
//! It is therefore highly recommended that you pass a pointer to a structure to fill in.
GEOMLIBEXPORT MAPPROJPARM * TransGenGetInputProj (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   MAPPROJPARM *projparm               //!< Projection parameter structure to fill in
   );

//! Get input object-map affine transformation if possible.
//!
//! @return Error code < 0
//! An error (EBadFuncParm) will be returned if the object-map transformation is not affine.
GEOMLIBEXPORT int TransGenGetInputTransAffine (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   MAT3X3 ItoO,                        //!< Input to output transformation returned
   MAT3X3 OtoI                         //!< Output to input transformation returned
   );

//! Get number of "pieces" for piecewise transformations.
//!
//! @return Number of "pieces"
GEOMLIBEXPORT int TransGenGetNumPieces (
   const TRANSPARM *tp,                //!< Transformation parameter structure
   UINT32 flags
   );

//! Get output transformation model.
//!
//! @return Transformation model
GEOMLIBEXPORT UINT16 TransGenGetOutputModel (
   const TRANSPARM *tp                 //!< Transformation parameter structure
   );

//! Get "output projection parameters" from TRANSPARM.
//!
//! @return See below
//! If a non-NULL value is passed for "projparm" then a pointer to this structure will be
//! returned.  If NULL is passed for "projparm" then either NULL or a pointer to an internal
//! projection parameter structure will be returned depending on whether a projection has
//! previously been specified via TransGenSetOutputProj() or TransGenSetOutputProjHandle().
//! It is therefore highly recommended that you pass a pointer to a structure to fill in.
GEOMLIBEXPORT MAPPROJPARM * TransGenGetOutputProj (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   MAPPROJPARM *projparm               //!< Projection parameter structure to fill in
   );

//! Get outpu object-map affine transformation if possible.
//!
//! @return Error code < 0
//! An error (EBadFuncParm) will be returned if the object-map transformation is not affine.
GEOMLIBEXPORT int TransGenGetOutputTransAffine (
   const TRANSPARM *transparm,         //!< Transformation parameter structure
   MAT3X3 ItoO,                        //!< Input to output transformation returned
   MAT3X3 OtoI                         //!< Output to input transformation returned
   );

//! Return array of points defining "piece" for piecewise transformation.
//!
//! @return Array of points
GEOMLIBEXPORT int TransGenGetPiece (
   const TRANSPARM *tp,
   int piecenum,
   DPOINT2D **points,
   int *numpoints,
   UINT32 flags
   );

//! Initialize TRANSPARM structure.
//!
//! @return Error code < 0
GEOMLIBEXPORT int TransGenInit (
   TRANSPARM *transparm                //!< Transformation parameter structure
   );

//! Determine if transformation is "affine".
//!
//! @return TRUE if transformation is affine, FALSE if not
inline bool TransGenIsAffine (
   const TRANSPARM *transparm          //!< Transformation parameter structure
   ) {
   return (transparm->IsAffineAll != 0);
   }

//! Determine if transformation results in change between right-hand and left-hand system.
//!
//! @return TRUE if transformation results in change, FALSE if not
GEOMLIBEXPORT int TransGenIsFlipped (
   const TRANSPARM *tp,
   const DPOINT2D *pt,
   bool fwd = true
   );

//! Determine if transformation has been "initialized".
//!
//! @return TRUE if transformation has been initialized, FALSE if not
inline bool TransGenIsInitialized (
   const TRANSPARM *transparm          //!< Transformation parameter structure
   ) {
   return (transparm->InitDone != 0);
   }

//! Determine if transformation is "identity".
//!
//! @return TRUE if transformation is identity, FALSE if not
inline bool TransGenIsIdentity (
   const TRANSPARM *transparm          //!< Transformation parameter structure
   ) {
   return (transparm->IsIdentityAll != 0);
   }

//! Determine if transformation is reversible.
//!
//! @return TRUE if transformation is reversible, FALSE if not
inline bool TransGenIsReversible (
   const TRANSPARM *transparm          //!< Transformation parameter structure
   ) {
   return (transparm->IsReversible != 0);
   }

//! Set full transformation to approximated affine if within tolerance.
//!
//! @return Error code < 0
//! Flags:
//!      TRANSGENCOORD_Output                Rectangle is in "output" coordinates (tolerance in "input" coordinates)
GEOMLIBEXPORT int TransGenSetAffineApprox (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const DRECT2D *rect,                //!< Rectangle over which to compute approximation
   double tolerance,                   //!< Maximum displacement in opposite coordinates from "rect"
   UINT32 flags                        //!< Used to determine coordinates
   );

//! Set whether to insert new points when doing TransGenConvPoints...().
GEOMLIBEXPORT void TransGenSetDoInsert (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   UINT8 doinsert                      //!< TRUE if point insertion is allowed, FALSE if not
   );

//! Set whether or not to extrapolate points outside defined boundaries.
//!
//! If extrapolation is not enabled then an error -may- be returned for points outside the defined
//! extents.  This is the default condition and will generally be much faster than extrapolating.
GEOMLIBEXPORT void TransGenSetExtrapOutside (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   UINT8 extrapoutside                 //!< TRUE if extrapolation desired, FALSE if not
   );

//! Temporarily set full transformation to specified affine matrices.
//!
//! @return 0
//! This will override the values set in the TRANSPARM structure until the next TransGenSet...()
//! or TransGenUpdate() operation.
GEOMLIBEXPORT int TransGenSetFullTransAffine (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const MAT3X3 ItoO,                        //!< Input to output transformation returned
   const MAT3X3 OtoI                         //!< Output to input transformation returned
   );

//! Set boundaries for valid transformation in input coordinates.
//!
//! Using this function will ensure that all points within the specified rectangle will have a valid
//! conversion for the forward transformation, assuming that their map coordinates are reasonable.
//! Points outside the rectangle may or may not have a valid transformation depending on the type of
//! transformation being performed.  This function is needed for some of the piecewise transformations
//! which are defined by the convex hull of the defining control point mesh.
GEOMLIBEXPORT ERRVALUE TransGenSetInputBound (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const DRECT2D *boundrect            //!< Bounding rectangle in input coordinates
   );

//! Set maximum displacement for point insertion, input coordinates
GEOMLIBEXPORT void TransGenSetInputInsertMaxError (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   double MaxError                     //!< Max error
   );

//! Set "input projection" in TRANSPARM structure.
GEOMLIBEXPORT ERRVALUE TransGenSetInputProj (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const MAPPROJPARM *projparm         //!< Projection parameters (pass NULL if no projection)
   );

//! Set "input projection" using given gctp handle (assumes handle is initialized).
//!
//! This makes a copy of the handle, so any subsequent changes to it will have no effect on the TRANSPARM
GEOMLIBEXPORT ERRVALUE TransGenSetInputProjHandle (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   void *gctphandle                    //!< CCTP handle (must have been initialized via gctpSetParm() already)
   );

//! Set "input transformation" to specified affine matrices.
//!
//! @return 0
GEOMLIBEXPORT int TransGenSetInputTransAffine (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const MAT3X3 ItoM,                  //!< Input to Map transformation matrix
   const MAT3X3 MtoI                   //!< Map to Input transformation matrix
   );

//! Set "input transformation" using given control points and model.
GEOMLIBEXPORT ERRVALUE TransGenSetInputTransCtrlPoint (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const CTRLPOINT3 *ctrlpoint,        //!< Control point array
   int NumPoints,                      //!< Number of control points
   UINT16 transmodel                   //!< Transformation model: TRANS2DMODEL_...
   );

//! Set "input transformation" to identity (implied).
//!
//! @return 0
GEOMLIBEXPORT int TransGenSetInputTransIdentity (
   TRANSPARM *transparm             //!< Transformation parameter structure
   );

//! Set maximum number of vertices to insert between pair of points.
//! Default maximum is 256.
GEOMLIBEXPORT void TransGenSetMaxInsertVertices (
   TRANSPARM *transparm,            //!< Transformation parameter structure
   int MaxVertices                  //!< Maximum allowed vertices
   );

//! Set boundaries for valid transformation in output coordinates.
//!
//! Using this function will ensure that all points within the specified rectangle will have a valid
//! conversion for the inverse transformation, assuming that their map coordinates are reasonable.
//! Points outside the rectangle may or may not have a valid transformation depending on the type of
//! transformation being performed.  This function is needed for some of the piecewise transformations
//! which are defined by the convex hull of the defining control point mesh.
GEOMLIBEXPORT ERRVALUE TransGenSetOutputBound (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const DRECT2D *boundrect            //!< Bounding rectangle in input coordinates
   );

//! Set maximum displacement for point insertion, output coordinates.
GEOMLIBEXPORT void TransGenSetOutputInsertMaxError (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   double MaxError                     //!< Max error
   );

//! Set "output projection" in TRANSPARM structure.
GEOMLIBEXPORT ERRVALUE TransGenSetOutputProj (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const MAPPROJPARM *projparm         //!< Projection parameters (pass NULL if no projection)
   );

//! Set "output projection" using given gctp handle (assumes handle is initialized).
GEOMLIBEXPORT ERRVALUE TransGenSetOutputProjHandle (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   void *gctphandle                    //!< CCTP handle (must have been initialized via gctpSetParm() already)
   );

//! Set "output transformation" to specified affine matrices.
//!
//! @return 0
GEOMLIBEXPORT int TransGenSetOutputTransAffine (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const MAT3X3 OtoM,                  //!< Output to Map transformation matrix
   const MAT3X3 MtoO                   //!< Map to Output transformation matrix
   );

//! Set "output transformation" using given control points and model.
GEOMLIBEXPORT ERRVALUE TransGenSetOutputTransCtrlPoint (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   const CTRLPOINT3 *ctrlpoint,        //!< Control point array
   int NumPoints,                      //!< Number of control points
   UINT16 transmodel                   //!< Transformation model: TRANS2DMODEL_...
   );

//! Set "output transformation" to identity (implied).
//!
//! @return 0
GEOMLIBEXPORT int TransGenSetOutputTransIdentity (
   TRANSPARM *transparm                //!< Transformation parameter structure
   );

//! Set primary transformation direction.
//! 
//! The default transformation direction if not set explicitly is "forward".  This is used in
//! cases where the time to do a reverse transformation is much higher than in the primary direction.
//! This is commonly used for raster warping.
GEOMLIBEXPORT void TransGenSetPrimaryDirection (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   UINT8 directions                    //!< TRANSDIR_Forward or TRANSDIR_Inverse
   );

//! Setup generic transformation between objects in different projections.
GEOMLIBEXPORT ERRVALUE TransGenSetupObjProjTrans (
   TRANSPARM *transparm,               //!< Transformation parameter structure
   MAT3X3 AtoM,                        //!< Object A -> Map
   MAT3X3 MtoA,                        //!< Map -> Object A
   MAPPROJPARM *Aprojparm,             //!< Projection parameters for object A
   MAT3X3 BtoM,                        //!< Object B -> Map
   MAT3X3 MtoB,                        //!< Map -> Object B
   MAPPROJPARM *Bprojparm              //!< Projection parameters for object B
   );

//! TRANSFUNC-style conversion function for forward transformation.
//!
//! This function is suitable for use in all functions which take a TRANSFUNC, including
//! MfCopyObjectT(), MfCopySubObjectsT(), etc.  Pass a pointer to the appropriate TRANSPARM structure
//! as the data associated with the TRANSFUNC.
GEOMLIBEXPORT ERRVALUE TransGenTransFuncFwd (
   void *ipoint,
   void *opoint,
   int numpoints,
   int numdim,
   void *vtp
   );

//! TRANSFUNC-style conversion function for inverse transformation.
//!
//! This function is suitable for use in all functions which take a TRANSFUNC, including
//! MfCopyObjectT(), MfCopySubObjectsT(), etc.  Pass a pointer to the appropriate TRANSPARM structure
//! as the data associated with the TRANSFUNC.
GEOMLIBEXPORT ERRVALUE TransGenTransFuncInv (
   void *ipoint,
   void *opoint,
   int numpoints,
   int numdim,
   void *vtp
   );

//! Update transformation after any changes and determine most efficient method.
GEOMLIBEXPORT void TransGenUpdate (
   TRANSPARM *transparm                //!< Transformation parameter structure
   );

#if defined(__cplusplus)
}

//! Disect a transformation into component parts (scale, rotation, shear).
inline int DisectGen2D (
   const DPOINT2D_OLD *point,          //!< Point to compute values at
   double size,                        //!< Size in source coordinates over which to compute (usually 1.0)
   double *xscale,                     //!< X scale at specified point returned
   double *yscale,                     //!< Y scale at specified point returned
   double *rotangle,                   //!< Rotation angle at specified point returned (radians)
   double *shear,                      //!< Shear angle at specified point returned (radians)
   TRANSFUNC transfunc,                //!< Transformation function to "disect"
   void* transdata                     //!< "userdata" for transfunc
   ) {
   return (DisectGen2D((const DPOINT2D*)point, size, xscale, yscale, rotangle, shear, transfunc, transdata));
   };

#endif


#endif

---