mi32/tinfuncs.h

Go to the documentation of this file.

/********************************************************************
*
* mi32/tinfuncs.h - TIN manipulation functions include file
*
* \if NODOC
* $Id: tinfuncs.h_v 1.36 2003/09/15 13:49:56 fileserver!dwilliss Exp $
*
* $Log: tinfuncs.h_v $
* Revision 1.36  2003/09/15 13:49:56  fileserver!dwilliss
* Doxygen
*
* Revision 1.35  2002/10/04 21:46:04  scowan
* nc.
*
* Revision 1.34  2001/12/27 18:32:21  scowan
* More const for parms.
*
* Revision 1.33  2000/10/10 21:39:57  msmith
* Genitor documentation.
*
* Revision 1.32  2000/09/01 13:16:02  mju
* Include rvcqtree.h for QTREEHANDLE defn.
*
* Revision 1.31  2000/08/31 21:51:54  scowan
* Undo changes.
*
* Revision 1.30  2000/05/12 16:00:22  scowan
* Added grouping.
*
* Revision 1.29  1999/10/20 20:43:49  mju
* const filenames.
*
 * Revision 1.28  1999/10/04  21:03:33  scowan
 * Fixed elem type changes.
 *
* Revision 1.27  1999/07/30 21:57:08  dfrolov
* add MfTINMerge() function
*
 * Revision 1.26  1999/05/26  16:00:15  mju
 * Add headers and forward declarations so will compile on own.
 *
*
* \endif
*********************************************************************/

#ifndef  INC_MI32_TINFUNCS_H
#define  INC_MI32_TINFUNCS_H

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

#ifndef  INC_MI32_FNAMEMAX_H
#include <mi32/fnamemax.h>
#endif

#ifndef  INC_MI32_ELEMTYPE_H
#include <mi32/elemtype.h>
#endif

#ifndef  INC_MI32_RVCQTREE_H
#include <mi32/rvcqtree.h>
#endif

/* Forward declarations */

struct RVCTININFO;
struct RVCTINEDGE;
struct DBLISTELMT;


typedef void* TEHANDLE;

struct MftAnyCallbackStruct {
   TEHANDLE th;
   UINT32 reason;
   INT32 ElemNum;
   INT32 OtherElemNum;        //!<  Set if reason is a Delete 
   ELEMTYPE ElemType;
   };

struct TEDCBL {
   void (*NotifyCB)(MftAnyCallbackStruct*, void*);
   void *NotifyUserData;
   TEDCBL *next;
   };

#define MftCR_Add          0x00000001
#define MftCR_Delete       0x00000002
#define MftCR_MoveBegin    0x00000004
#define MftCR_MoveEnd      0x00000008

#define MftSave_ComputeStat 0x00000001
#define MftRebuild_Hulls    0x00000002

#define TINCLIPMODE_Include   1
#define TINCLIPMODE_Exclude   2

struct TEDITINFO {
   UNICODE filename[FILENAME_MAX];
   int findex;                      //!<  Handle to open RVC file 
   int TINid;                       //!<  Handle to open tin object 
   int dbid;                        //!<  TIN database handle 
   RVCTININFO *Info;
   double SnapDist;
   UINT32 SnapOpt;
   QTREEHANDLE triQtree;
   QTREEHANDLE nodeQtree;
   QTREEHANDLE edgeQtree;
   bool WasPreOpened;
   bool EnableCallback;
   bool IsChanged;      //!<  set to 1 if any changes was made 
   TEDCBL *NotifyCBList;
   UINT32 flags;
   
   //! Call notify callback.
   void CallNotifyCallback (
      UINT32 reason, 
      ELEMTYPE ElemType, 
      INT32 ElemNum, 
      INT32 OtherElemNum
      );

   //! Remove all q-tree from the memory.
   ERRVALUE ShutdownQTrees (
      );
      
   };
   

#define MFTFLAG_NoSaveQTree      0x00000010

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

//!:Associate with "TIN Toolkit"
//!\addtogroup TINToolkit TIN Toolkit
//!@{

//! Initialize TIN toolkit handle.
//!
//! @return TIN Handle
TEHANDLE MftInit (
   void
   );

//! Open TIN object and setup.
int MftOpen (
   TEHANDLE vh,                        //!< TIN toolkit handle
   const UNICODE *filename,            //!< Filename to open
   INT32 inode,                        //!< Inode of TIN object
   RVCTININFO *vinfo,                  //!< TIN info
   UINT32 flags                        //!< Flags
   );

//! Setup TIN toolkit for specified TIN object.
int MftSetup (
   TEHANDLE vh,                        //!< TIN toolkit handle
   int id,                             //!< Id of TIN object
   RVCTININFO *tinfo,                  //!< TIN info
   UINT32 flags                        //!< Flags
   );

//! Create new TIN object and initialize toolkit
int MftNew (
   TEHANDLE vh,                        //!< TIN toolkit handle
   const UNICODE *filename,            //!< Filename to open
   RVCTININFO *Info,                   //!< TIN info
   UINT32 flags                        //!< Flags
   );

//! Get TIN handle.
//!
//! @return TIN id
int MftGetHandle (
   TEHANDLE th                         //!< TIN toolkit handle
   );

//! Enable/disable callback calls.
int MftEnableCallbacks (
   TEHANDLE vh,                        //!< TIN toolkit handle
   bool Flag                           //!< Enable / disable callback flag
   );

//! Recompute extents for whole TIN object.
int MftComputeExtents (
   TEHANDLE th                         //!< TIN toolkit handle
   );

//! Close current TIN object.
int MftClose (
   TEHANDLE th,                        //!< TIN toolkit handle
   UINT32 flags                        //!< Flags
   );

//! Save TIN object in the suppled object.
int MftSave (
   TEHANDLE th,                        //!< TIN toolkit handle
   int dfindex,
   RVCGENINFO *geninfo,
   UINT32 flags                        //!< Flags
   );

//! Set flags.
UINT32 MftSetFlags (
   TEHANDLE vh,                        //!< TIN toolkit handle
   UINT32 flags                        //!< Flags
   );

//! Assign notify callback.
void MftSetNotifyCallback (
   TEHANDLE th,                        //!< TIN toolkit handle
   void (*NotifyCB)(MftAnyCallbackStruct*, void*), //! Callback function
   void *udata                         //!< Callback data
   );

//! Remove previously assigned notify callback.
void MftRemoveNotifyCallback (
   TEHANDLE th,                        //!< TIN toolkit handle
   void (*NotifyCB)(MftAnyCallbackStruct*, void*)  //! Callback function
   );

//! Does nothing now.
void MftSetDatabaseMode (
   TEHANDLE th,                        //!< TIN toolkit handle
   int ElemType,                       //!< Element type
   UINT32 dbtype                       //!< Database type
   );

//! Get qtree handle for specified element.
void *MftGetQTree (
   TEHANDLE th,                        //!< TIN toolkit handle
   int ElemType                        //!< Element type
   );

//! Get number of element of specified type.
INT32 MftGetNumElements (
   TEHANDLE th,                        //!< TIN toolkit handle
   int ElemType                        //!< Element type
   );

//! Does nothing now.
int MftGetDBHandle (
   TEHANDLE th,                        //!< TIN toolkit handle
   int ElemType                        //!< Element type
   );

//! Does nothing now.
int MftGetStyleHandle (
   TEHANDLE th                         //!< TIN toolkit handle
   );

//! Get extents for specified element.
int MftGetElemRect (
   TEHANDLE vh,                        //!< TIN toolkit handle
   int ElemType,                       //!< Element type
   INT32 ElemNum,                      //!< Element number
   DRECT2D *rect                       //!< Extents rectangle returned
   );

//! Get internal z-value of TIN node.
//!
//! @return z-value
double MftGetZValue (
   TEHANDLE th,                        //!< TIN toolkit handle
   int ElemType,                       //!< Element type
   INT32 ElemNum                       //!< Element number
   );

//! Set internal z-value (for TIN node).
int MftSetZValue (
   TEHANDLE vh,                        //!< TIN toolkit handle
   int ElemType,                       //!< Element type
   INT32 ElemNum,                      //!< Element number
   double zvalue                       //!< Z-value
   );

//! Set qtree handle for specified ELEMENTTYPE.
void MftSetQTree (
   TEHANDLE vh,                        //!< TIN toolkit handle
   int ElemType,                       //!< Element type
   QTREEHANDLE qtree                   //!< Qtree handle
   );

//! Close & free TIN toolkit.
void MftStop (
   TEHANDLE th                         //!< TIN toolkit handle
   );

//! Add a "hard edge" breakline to the TIN structure.
int MftAddLine (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOINT3D *Line,                     //!< Line to add
   INT32 Num                           //!< Number of points in line
   );

//! Add a "hard edge" breakline to the TIN structure, with elevation control.
int MftAddLineExt (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOINT3D *Line,                     //!< Line to add
   INT32 Num,                          //!< Number of points in line
   int HasElevation                    //!< Set to TRUE if this is a "real" 3D line, otherwise set to FALSE
   );

//! Add new node to the TIN structure.
int MftAddNode (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOINT3D *P                         //!< New node location
   );

//! Add new node to TIN.
int MftAddNodeExt (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOINT3D *P,                        //!< New node location
   int TryOutside
   );

//! Add breaklines to the TIN structure from the vector object.
int MftAddVectorBreaklines (
   TEHANDLE th,                        //!< TIN toolkit handle
   const UNICODE *filename,                  //!< Vector filename
   INT32 inode,                        //!< Vector object inode
   INT32 gvectinode                    //!< Inode of the georeference subobject to use
   );

//! Add a breakline to the TIN structure as a 2 point segment.
int MftAddSegment (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOINT3D *start,                    //!< Start point
   DPOINT3D *end,                      //!< End point
   UINT8 type,                         //!< 0 for "soft" edge, TINEDGE_Hard for "hard" edge
   int HasElevation                    //!< Number of points in line - not set when breakline doesn't have an elevation
   );

//! Remove all triangles that fall within given list of exclude areas (polygons).
int MftApplyExclude (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOLYGON *Exclude,                  //!< List of polygons
   INT32 NumExclude                    //!< Number of exclude polygons
   );

//! Create list of connected edges for each node (Node-to-Edge link table).
int MftBuildNodeToEdgeLinks (
   TEHANDLE th                         //!< TIN toolkit handle
   );

//! Clip TIN structure using vector object.
int MftClipByVector (
   TEHANDLE th,                        //!< TIN toolkit handle
   const UNICODE *filename,                  //!< Vector filename
   INT32 inode,                        //!< Vector object inode
   INT32 gvectinode,                   //!< Inode of the georeference subobject to use
   int ClipMode                        //!< Flag: TINCLIPMODE_Include or TINCLIPMODE_Exclude
   );

//! Compute z-value for a given x,y location.
int MftComputeElevation (
   TEHANDLE thandle,                   //!< TIN toolkit handle
   DPOINT3D *P                         //!< Point to calculate z-value from
   );

//! Compute standart statistics for TIN triangles.
int MftComputeStatistics (
   TEHANDLE th                         //!< TIN toolkit handle
   );

//! Create TIN from scratch or replace existing TIN.
int MftCreateTIN (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOINT3D *Nodes,                    //!< List of input points
   INT32 NumNodes,                     //!< Number of input points
   DOUBLE zscale,                      //!< Scale coeff
   DOUBLE zoffset,                     //!< Offset coeff
   DOUBLE xytolerance                  //!< Tolerance, minim. allowed distance between points
   );

//! Create TIN from scratch with minimized memory usage.
//!
//! NO QTREE WILL BE MAINTAINED !!!
//! THIS FUNCTIONS IS NOT FOR USAGE WITHIN TNTedit!
int MftCreateTINBatch (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOINT3D **Data,
   INT32 NumNodes,                     //!< Number of nodes
   DOUBLE zscale,                      //!< Z scale
   DOUBLE zoffset,                     //!< Z offset
   DOUBLE xytolerance                  //!< XY tolerance
   );

//! Delete given node and recompute triangulation in affected area.
int MftDeleteNode (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 Num                           //!< Node number to delete
   );

//! Delete set of nodes.
int MftDeleteNodes (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 *NodeList,                    //!< Nodes to delete
   INT32 Nums                          //!< Number of nodes
   );

//! Delete set of nodes.
int MftDeleteNodesHole (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 *NodeList,                    //!< Nodes to delete
   INT32 Nums                          //!< Number of nodes
   );

//! Delete node from tin object and make a hole there.
//!
//! IMPORTANT: Do not use this function to delete more than one node,
//!      UNLESS you have sorted NodeNum in descending order.
//!      Node numbers might changed after each call.
int MftDeleteNodeHole (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 NodeNum                       //!< Number of node
   );

//! Delete set of triangles.
int MftDeleteTriangles (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 *List,                        //!< Triangles to delete
   INT32 Nums                          //!< Number of triangles
   );

//! Make a "hole" from triangle.
//!
//! IMPORTANT: Do not use this function to delete more than one triangle,
//!      UNLESS you have sorted Nums in descending order.
//!      Triangle numbers might changed after each call.
int MftDeleteTriangleHole (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 Num                           //!< Triangle number
   );

//! Delete edge (and 2 adj. triangles) and make a hole in the TIN.
//!
//! IMPORTANT: Do not use this function to delete more than one edge,
//!      UNLESS you have sorted Nums in descending order.
//!      Edge numbers might changed after each call.
int MftDeleteEdgeHole (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 Num                           //!< Edge Number
   );

//! Delete set of edges.
int MftDeleteEdges (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 *List,                        //!< Edges to delete
   INT32 Nums                          //!< Number of edges
   );

//! Get list of all nodes connected to given node.
//!
//! @return number of nodes - on success, < 0 on error.
//! NOTE: this function assumes that TIN object has node-to-edge links,
//!       if not call MftBuildNodeToEdgeLinks(..) function.
int MftGetConnectedNodeList (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 Num,                          //!< Node number
   INT32 **list                        //!< List of node numbers returned
   );

//! Get orienation for the given edge.
//!
//! NOTE: angle measured in radians
int MftGetEdgeAzimuth (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 NodeNum,                      //!< Node number that will be a start point
   RVCTINEDGE *Edge,                   //!< Edge description (passed)
   DOUBLE *Angle                       //!< Orientation angle (returned)
   );

//! General function for building TINs.
//!   AVOID USING THIS FUNCTION UNLESS YOUR COMPLETELY UNDERSTAND
//!   THE FOLLOWING INFORMATION. USE SPECIALIZED FUNCTIONS INSTEAD.
//!
//! WARNING: This function intended to rebuild topology for entire TIN or add
//! one hull (!). If programmer wants to rebuild entire TIN and not to use
//! any cliping areas or exclude areas - set all NumNodes, NumEdges and
//! NumTriangles to zero. Otherwise, this function will add new elements
//! to the end of each table. If programmer wants to build complex TIN
//! object with multiple hulls - call this function for each separate hull.
//! Programmers needs in this case description of "CLIP" polygon and
//! list of exclude areas. Clip polygon can be only one per hull.
//! WARNING: if you want to rebuild entire tin object do not forget to
//! set minval and maxval before calling this function to DBL_MAX & DBL_MIN.
//!
//! Note : This function will NOT UPDATE hull structure unless flag is set.
//! ATTENTION: This function will update QTrees.
//! ATTENTION: New nodes should be not in Qtree structure before calling
//! this function - in this case there will be a redundancy.
int MftGenerateTIN (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOINT3D *Pool,                     //!< Input points, not necessary all points should belong to this hull
   INT32 NumPoints,                    //!< Number of input points
   DPOLYGON *Clip,                     //!< Clip polygon
   DPOLYGON *Exclude,                  //!< List of exclude areas
   INT32 NumExclude,                   //!< Number of exclude areas in the previous list
   INT32 Flag                          //!< Flag: 1 - update all hull strcutures, 0 - skip
   );

//! Get sorted list of edges that connected to this node.
//!
//! @return number of edges or error if < 0
//! IMPORTANT: This function assumes that there is no Node-to-Edge link
//!      table in TIN object. This function used to build such list.
INT32 MftGetNodeEdges (
   TEHANDLE vh,                        //!< TIN toolkit handle
   INT32 Num,                          //!< Node number
   INT32 **edgelist                    //!< List of edge numbers returned
   );

//! Get a list of tin nodes as DPOINT3D/DPOINT2D/RVCTINNODE array.
int MftGetNodes (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 NodeNum,                      //!< Node number
   INT32 *NumNodes,                    //!< Number of connected nodes returned
   void  **Array,                      //!< Nodes data returned
   INT32 **List,                       //!< List of connected node numbers
   INT32 flag                          //!< if flag = 0, output is RVCTINNODE, 1 - DPOINT3D, 2 - DPOINT2D
   );

//! Compute plane equation coefficients for given triangle.
//!
//! NOTE: a * x + b * y + c * z + d = 0
int MftGetPlaneEquation (
   TEHANDLE thandle,                   //!< TIN toolkit handle
   INT32 TriNum,                       //!< Triangle number
   DOUBLE* a,                          //!< X coefficient returned
   DOUBLE* b,                          //!< Y coefficient returned
   DOUBLE* c,                          //!< Z coefficient returned
   DOUBLE *d                           //!< offset returned
   );

//! Get list of triangles which have given node as vertex.
int MftGetSurroundTriangles (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 NodeNum,                      //!< Node number
   INT32 **TriList,                    //!< List of triangles returned
   INT32 **EdgeList,                   //!< List of surround edges returned
   INT32 **NodeList,                   //!< List of surround nodes returned
   INT32 *trinum,                      //!< Number of triangles
   INT32 *edgenum,                     //!< Number of edges
   INT32 *nodenum                      //!< Number of nodes
   );

//! Get list of triangles that are within (even partially) given polygon.
int MftGetTrianglesPoly (
   TEHANDLE th,                        //!< TIN toolkit handle
   DPOLYGON *poly,                     //!< Polygon description
   INT32 **TList,                      //!< List of triangles  returned
   INT32 *num                          //!< Number of triangles returned
   );

//! Filter TIN structure.
int MftMedianFiltering (
   TEHANDLE thandle                    //!< TIN toolkit handle
   );

//! Recreate hull structures.
//!
//! 1. Read edges and find any that has "universe" triangle as neighbor.
//! 2. Start tracing hull from this point until "chain" will be closed
//! 3. Determine is it "universe" or "exclude" hull
//! 4. Save information about this hull and start again until any unprocessed
//!    edge exists. All processed edges are marked in the binary array.
int MftRebuildHulls (
   TEHANDLE th                         //!< TIN toolkit handle
   );

//! Rebuild entire TIN as one hull without any respect to exclude areas.
int MftRebuildTIN (
   TEHANDLE th                         //!< TIN toolkit handle
   );

//! Recover from the undo operation.
ERRVALUE MftRecoverFromUndo (
   TEHANDLE th                         //!< TIN toolkit handle
   );

//! Removes nodes that connected to nodes with z-value equal to its own.
//!
//! This function removes FLAT TRIANGLES using tolerance.
int MftRemoveFlatNodes (
   TEHANDLE thandle,                   //!< TIN toolkit handle
   DOUBLE dz,                          //!< Tolerance: max. allowed difference in z-values
   DOUBLE minedge                      //!< Minimum edge length between 2 nodes that are within dz-tolerance
   );

//! This function will delete edges that are longer than specified length and create empty holes in those areas.
int MftRemoveLongEdges (
   TEHANDLE th,                        //!< TIN toolkit handle
   DOUBLE distance                     //!< Maximum possible distance
   );

//! Validate TIN topology for entire object.
//!
//! THIS FUNCTION CAN'T FIX TOPOLOGY!
int MftValidateTINTopology (
   TEHANDLE th,                        //!< TIN toolkit handle
   INT32 flag                          //!< If flag equals to 0 process will not check node-edge connectivity
   );

//! This function blindly combines 2 TINs (using georeference) into one, and recomputes topology.
//!
//! This function is not a member of TIN toolkit, but it uses it internally.
//! Georeference handling: The output TIN object will have a georeference
//! based on first (A) TIN object.
int MfTINMerge (
   int idA,                            //!< Input TIN object 1
   INT32 ginodeA,                      //!< Georeference inode for TIN object 1
   int idB,                            //!< Input TIN object 2
   INT32 ginodeB,                      //!< Georeference inode for TIN object 2
   RVC::OBJITEM& ObjItem            //!< output object
   );

//!@}

#if defined(__cplusplus)
}
#endif

#endif

---