NAME

wkb2wkt, wkt2wkb, emitwkb, freewkb - manipulate Well-Known Binary (WKB) and Well-Known Text (WKT) representations

SYNOPSIS

   #include 
   WKBResult *wkt2wkb(char *wktstring);

   char *wkb2wkt(char *filename);

   void emitwkb(WKBResult *r, int type, FILE *fp);

   void freewkb(WKBResult *r);

DESCRIPTION

wkt2wkb() creates a data structure (see Data Structures below) from a string containing a WKT representation. The data structure result must be freed by the calling program using the freewkb() function.

wkb2wkt() creates a string from the specified file (presumed to contain a WKB). The string returned must be freed by the calling program using free().

emitwkb() emits the information contained in the WKBResult data structure (see Data Structures below) as specified in the type argument to the file given by the fp argument. fp is assumed to be a pointer to a file opened for writing.

freewkb() frees memory allocated by the wkt2wkb() function.

The type argument must be one of:
WKTBINARY cause the output format to be the WKB format.
WKTHEX cause the output format to be the hexidecimal verion of the WKB format.
WKTDEBUG cause the output format to be the verbose textual representation format.

Data Structures

The data structures used by these library functions are shown below:

The first is the WKBResult data structure:

   typedef struct _WKBResult {
       int result_type;
       union _rvalue {
           WKBGeometry *g_val;
           WKBGeometryCollection *gc_val;
       } result_value;
   } WKBResult;

result_type is either WKBGEOMETRY or WKBGEOMETRYCOLLECTION.

WKBGeometryCollection is defined as:

   typedef struct _WKBGeometryCollection {
       byte byteorder;
       uint32 wkbType;
       uint32 num_wkbGeometries;
       WKBGeometry *wkbGeometries;
   } WKBGeometryCollection;

byte is defined as:

      typedef char byte;

uint32 is defined as:

      typedef unsigned int uint32;

WKBGeometry is defined as:

   typedef struct _WKBGeometry {
       int geometry_type;
       union _gvalue {
           WKBPoint *point;
           WKBLineString *linestring;
           WKBPolygon *polygon;
           WKBMultiPoint *multipoint;
           WKBMultiLineString *multilinestring;
           WKBMultiPolygon *multipolygon;
       } value;
   } WKBGeometry;

geometry_type is one of:

  • WKBPOINT,
  • WKBLINESTRING,
  • WKBPOLYGON,
  • WKBMULTIPOINT,
  • WKBMULTILINESTRING, or
  • WKBMULTIPOLYGON.
  • NOTE: The geometry_type member is not strictly called out in revison 1.0 of the SQL specification. This is due, in part, to the fact the the current revision does not allow hetero- geneous collections.

    The remainder of the data structures given here are self- explanatory:

       typedef struct _point {
           double x;
           double y;
       } Point;
    
       typedef struct _linearRing {
           uint32 numPoints;
           Point *points;
       } LinearRing;
    
       typedef struct _WKBPoint {
           byte byteorder;
           uint32 wkbType;
           Point point;
       } WKBPoint;
    
       typedef struct _WKBLineString {
           byte byteorder;
           uint32 wkbType;
           uint32 numPoints;
           Point *points;
       } WKBLineString;
    
       typedef struct _WKBPolygon {
           byte byteorder;
           uint32 wkbType;
           uint32 numRings;
           LinearRing *rings;
       } WKBPolygon;
    
       typedef struct _WKBMultiPoint {
           byte byteorder;
           uint32 wkbType;
           uint32 num_wkbPoints;
           WKBPoint *wkbPoints;
       } WKBMultiPoint;
    
       typedef struct _WKBMultiLineString {
           byte byteorder;
           uint32 wkbType;
           uint32 num_wkbLineStrings;
           WKBLineString *wkbLineStrings;
       } WKBMultiLineString;
    
       typedef struct _WKBMultiPolygon {
           byte byteorder;
           uint32 wkbType;
           uint32 num_wkbPolygons;
           WKBPolygon *wkbPolygons;
       } WKBMultiPolygon;
    

    RETURN VALUES

    wkb2wkt()

    returns a null pointer if an error occurs.

    The character string wkberrmsg will contain a textual description of the error which is flagged by the integer wkberr. Both of these are defined in the header file "wkb.h".

    wkberr is one of

    E_BINFILE could not open input binary file
    E_UBO a problem with the input binary, byte order unknown
    E_UT a problem with the input binary, type unknown

    wkt2wkb()

    returns a null pointer if an error occurs.

    The character string wkterrmsg will contain a textual description of the error which is flagged by the integer wkterr. Both of these are defined in the header file "wkb.h".

    wkterr is one of

    E_TMPOUT could not open temporary working file for output
    E_TMPIN could not open temporary working file for input
    E_NOINPUT the input string is empty