gxfopen.h File Reference

#include "cpl_conv.h"
#include "cpl_string.h"

Go to the source code of this file.

Classes

struct  GXFInfo_t

Functions

GXFHandle GXFOpen (const char *pszFilename)
CPLErr GXFGetRawInfo (GXFHandle hGXF, int *pnXSize, int *pnYSize, int *pnSense, double *pdfZMin, double *pdfZMax, double *pdfDummy)
CPLErr GXFGetRawScanline (GXFHandle, int iScanline, double *padfLineBuf)
CPLErr GXFGetScanline (GXFHandle, int iScanline, double *padfLineBuf)
char ** GXFGetMapProjection (GXFHandle)
char ** GXFGetMapDatumTransform (GXFHandle)
char * GXFGetMapProjectionAsPROJ4 (GXFHandle)
char * GXFGetMapProjectionAsOGCWKT (GXFHandle)
CPLErr GXFGetRawPosition (GXFHandle, double *, double *, double *, double *, double *)
CPLErr GXFGetPosition (GXFHandle, double *, double *, double *, double *, double *)
void GXFClose (GXFHandle hGXF)

Detailed Description

Public GXF-3 function definitions.


Function Documentation

void GXFClose ( GXFHandle  hGXF  ) 

Close GXF file opened with GXFOpen().

Parameters:
hGXF handle to GXF file.
char** GXFGetMapDatumTransform ( GXFHandle  hGXF  ) 

Return the lines related to the datum transformation. It is up to the caller to parse them and interpret. The return result will be NULL if no MAP_DATUM_TRANSFORM line was found in the header.

Parameters:
hGXF the GXF file handle.
Returns:
a NULL terminated array of string pointers containing the datum, or NULL. The strings remained owned by the GXF API, and should not be modified or freed by the caller.
char** GXFGetMapProjection ( GXFHandle  hGXF  ) 

Return the lines related to the map projection. It is up to the caller to parse them and interprete. The return result will be NULL if no MAP_PROJECTION line was found in the header.

Parameters:
hGXF the GXF file handle.
Returns:
a NULL terminated array of string pointers containing the projection, or NULL. The strings remained owned by the GXF API, and should not be modified or freed by the caller.
char* GXFGetMapProjectionAsOGCWKT ( GXFHandle  hGXF  ) 

Return the GXF Projection in OpenGIS Well Known Text format.

The returned string becomes owned by the caller, and should be freed with CPLFree() or VSIFree(). The return value will be "" if no projection information is passed.

The mapping of GXF projections to OGC WKT format is not complete. Please see the gxf_ogcwkt.c code to better understand limitations of this translation. More information about OGC WKT format can be found in the OpenGIS Simple Features specification for OLEDB/COM found on the OpenGIS web site at www.opengis.org. The translation uses some code cribbed from the OGR library, about which more can be learned from http://gdal.velocet.ca/projects/opengis/.

For example, the following GXF definitions:

 UNIT_LENGTH                        
 m,1
 MAP_PROJECTION
 "NAD83 / UTM zone 19N"
 "GRS 1980",6378137,0.081819191,0
 "Transverse Mercator",0,-69,0.9996,500000,0
 

Would translate to (without the nice formatting):

   PROJCS["NAD83 / UTM zone 19N",
          GEOGCS["GRS 1980",
                 DATUM["GRS_1980",
                     SPHEROID["GRS 1980",6378137,298.257222413684]],
                 PRIMEM["unnamed",0],
                 UNIT["degree",0.0174532925199433]],
          PROJECTION["Transverse_Mercator"],
          PARAMETER["latitude_of_origin",0],
          PARAMETER["central_meridian",-69],
          PARAMETER["scale_factor",0.9996],
          PARAMETER["false_easting",500000],
          PARAMETER["false_northing",0],
          UNIT["m",1]]
 
Parameters:
hGXF handle to GXF file, as returned by GXFOpen().
Returns:
string containing OGC WKT projection.
char* GXFGetMapProjectionAsPROJ4 ( GXFHandle  hGXF  ) 

Return the GXF Projection in PROJ.4 format.

The returned string becomes owned by the caller, and should be freed with CPLFree() or VSIFree(). The return value will be "unknown" if no projection information is passed.

The mapping of GXF projections to PROJ.4 format is not complete. Please see the gxf_proj4.c code to better understand limitations of this translation. Noteable PROJ.4 knows little about datums.

For example, the following GXF definitions:

 UNIT_LENGTH                        
 m,1
 MAP_PROJECTION
 "NAD83 / UTM zone 19N"
 "GRS 1980",6378137,0.081819191,0
 "Transverse Mercator",0,-69,0.9996,500000,0
 

Would translate to:

 +proj=tmerc +lat_0=0 +lon_0=-69 +k=0.9996 +x_0=500000 +y_0=0 +ellps=GRS80
 
Parameters:
hGXF handle to GXF file, as returned by GXFOpen().
Returns:
string containing PROJ.4 projection.
CPLErr GXFGetPosition ( GXFHandle  hGXF,
double *  pdfXOrigin,
double *  pdfYOrigin,
double *  pdfXPixelSize,
double *  pdfYPixelSize,
double *  pdfRotation 
)

Get the grid positioning information.

Note that these coordinates refer to the grid positioning after taking into account the SENSE flag (as is done by the GXFGetScanline()) function.

Note that the pixel values are considered to be point values in GXF, and thus the origin is for the first point. If you consider the pixels to be areas, then the origin is for the center of the origin pixel, not the outer corner.

This function does not support vertically oriented images, nor does it properly transform rotation for images with a SENSE other than GXFS_UL_RIGHT.

Parameters:
hGXF the GXF file handle.
pdfXOrigin X position of the origin in the base coordinate system.
pdfYOrigin Y position of the origin in the base coordinate system.
pdfXPixelSize X pixel size in base coordinates.
pdfYPixelSize Y pixel size in base coordinates.
pdfRotation rotation in degrees counter-clockwise from the base coordinate system.
Returns:
Returns CE_None if successful, or CE_Failure if no posiitioning information was found in the file.
CPLErr GXFGetRawInfo ( GXFHandle  hGXF,
int *  pnXSize,
int *  pnYSize,
int *  pnSense,
double *  pdfZMin,
double *  pdfZMax,
double *  pdfDummy 
)

Fetch header information about a GXF file.

Note that the X and Y sizes are of the raw raster and don't take into account the SENSE flag. If the file is column oriented (rows in the files are actually columns in the raster) these values would need to be transposed for the actual raster.

The legal pnSense values are:

  • GXFS_LL_UP(-1): lower left origin, scanning up.
  • GXFS_LL_RIGHT(1): lower left origin, scanning right.
  • GXFS_UL_RIGHT(-2): upper left origin, scanning right.
  • GXFS_UL_DOWN(2): upper left origin, scanning down.
  • GXFS_UR_DOWN(-3): upper right origin, scanning down.
  • GXFS_UR_LEFT(3): upper right origin, scanning left.
  • GXFS_LR_LEFT(-4): lower right origin, scanning left.
  • GXFS_LR_UP(4): lower right origin, scanning up.

Note that the GXFGetScanline() function attempts to provide a GXFS_UL_RIGHT view onto files, but doesn't handle the *_DOWN and *_UP oriented files.

The Z min and max values may not occur in the GXF header. If they are requested, and aren't available in the header the entire file is scanned in order to establish them. This can be expensive.

If no DUMMY value was specified in the file, a default of -1e12 is used.

Parameters:
hGXF handle to GXF file returned by GXFOpen().
pnXSize int to be set with the width of the raw raster. May be NULL.
pnYSize int to be set with the height of the raw raster. May be NULL.
pnSense int to set with SENSE flag, may be NULL.
pdfZMin double to set with minimum raster value, may be NULL.
pdfZMax double to set with minimum raster value, may be NULL.
pdfDummy double to set with dummy (nodata / invalid data) pixel value.
CPLErr GXFGetRawPosition ( GXFHandle  hGXF,
double *  pdfXOrigin,
double *  pdfYOrigin,
double *  pdfXPixelSize,
double *  pdfYPixelSize,
double *  pdfRotation 
)

Get the raw grid positioning information.

Note that these coordinates refer to the raw grid, and are in the units specified by the UNITS field. See GXFGetPosition() for a similar function that takes into account the SENSE values similarly to GXFGetScanline().

Note that the pixel values are considered to be point values in GXF, and thus the origin is for the first point. If you consider the pixels to be areas, then the origin is for the center of the origin pixel, not the outer corner.

Parameters:
hGXF the GXF file handle.
pdfXOrigin X position of the origin in the base coordinate system.
pdfYOrigin Y position of the origin in the base coordinate system.
pdfXPixelSize X pixel size in base coordinates.
pdfYPixelSize Y pixel size in base coordinates.
pdfRotation rotation in degrees counter-clockwise from the base coordinate system.
Returns:
Returns CE_None if successful, or CE_Failure if no posiitioning information was found in the file.
CPLErr GXFGetRawScanline ( GXFHandle  hGXF,
int  iScanline,
double *  padfLineBuf 
)

Read a scanline of raster data from GXF file.

This function will read a row of data from the GXF file. It is "Raw" in the sense that it doesn't attempt to account for the SENSE flag as the GXFGetScanline() function does. Unlike GXFGetScanline(), this function supports column organized files.

Any dummy pixels are assigned the dummy value indicated by GXFGetRawInfo().

Parameters:
hGXF the GXF file handle, as returned from GXFOpen().
iScanline the scanline to read, zero is the first scanline in the file.
padfLineBuf a buffer of doubles into which the scanline pixel values are read. This must be at least as long as a scanline.
Returns:
CE_None if access succeeds or CE_Failure if something goes wrong.
CPLErr GXFGetScanline ( GXFHandle  hGXF,
int  iScanline,
double *  padfLineBuf 
)

Read a scanline of raster data from GXF file.

This function operates similarly to GXFGetRawScanline(), but it attempts to mirror data horizontally or vertically based on the SENSE flag to return data in a top to bottom, and left to right organization. If the file is organized in columns (SENSE is GXFS_UR_DOWN, GXFS_UL_DOWN, GXFS_LR_UP, or GXFS_LL_UP) then this function will fail, returning CE_Failure, and reporting a sense error.

See GXFGetRawScanline() for other notes.

Parameters:
hGXF the GXF file handle, as returned from GXFOpen().
iScanline the scanline to read, zero is the top scanline.
padfLineBuf a buffer of doubles into which the scanline pixel values are read. This must be at least as long as a scanline.
Returns:
CE_None if access succeeds or CE_Failure if something goes wrong.
GXFHandle GXFOpen ( const char *  pszFilename  ) 

Open a GXF file, and collect contents of the header.

Parameters:
pszFilename the name of the file to open.
Returns:
a handle for use with other GXF functions to access the file. This will be NULL if the access fails.

Generated on 2 Aug 2014 for GXF by  doxygen 1.6.1