gxfopen.h File Reference

Compounds
	struct	GXFInfo_t
Functions
	GXFHandle	GXFOpen ( const char * pszFilename )
		Open a GXF file, and collect contents of the header. More...
	CPLErr	GXFGetRawInfo ( GXFHandle hGXF, int pnXSize, int pnYSize, int pnSense, double pdfZMin, double * pdfZMax, double * pdfDummy )
		Fetch header information about a GXF file. More...
	CPLErr	GXFGetRawScanline ( GXFHandle, int iScanline, double * padfLineBuf )
		Read a scanline of raster data from GXF file. More...
	CPLErr	GXFGetScanline ( GXFHandle, int iScanline, double * padfLineBuf )
		Read a scanline of raster data from GXF file. More...
	char**	GXFGetMapProjection ( GXFHandle )
		Return the lines related to the map projection. More...
	char**	GXFGetMapDatumTransform ( GXFHandle )
		Return the lines related to the datum transformation. More...
	char*	GXFGetMapProjectionAsPROJ4 ( GXFHandle )
		Return the GXF Projection in PROJ.4 format. More...
	char*	GXFGetMapProjectionAsOGCWKT ( GXFHandle )
		Return the GXF Projection in OpenGIS Well Known Text format. More...
	CPLErr	GXFGetRawPosition ( GXFHandle, double , double , double , double , double * )
		Get the raw grid positioning information. More...
	CPLErr	GXFGetPosition ( GXFHandle, double , double , double , double , double * )
		Get the grid positioning information. More...
	void	GXFClose ( GXFHandle hGXF )
		Close GXF file opened with GXFOpen(). More...

Detailed Description

Function Documentation (1)

GXFHandle GXFOpen (const char * pszFilename)

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 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.

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 ** 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 * 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.

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.

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 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.

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.

gxfopen.h File Reference

Compounds

Functions

Detailed Description

Function Documentation (1)

GXFHandle GXFOpen (const char * pszFilename)

CPLErr GXFGetRawInfo (GXFHandle hGXF, int * pnXSize, int * pnYSize, int * pnSense, double * pdfZMin, double * pdfZMax, double * pdfDummy)

CPLErr GXFGetRawScanline (GXFHandle hGXF, int iScanline, double * padfLineBuf)

CPLErr GXFGetScanline (GXFHandle hGXF, int iScanline, double * padfLineBuf)

char ** GXFGetMapProjection (GXFHandle hGXF)

char ** GXFGetMapDatumTransform (GXFHandle hGXF)

char * GXFGetMapProjectionAsPROJ4 (GXFHandle hGXF)

char * GXFGetMapProjectionAsOGCWKT (GXFHandle hGXF)

CPLErr GXFGetRawPosition (GXFHandle hGXF, double * pdfXOrigin, double * pdfYOrigin, double * pdfXPixelSize, double * pdfYPixelSize, double * pdfRotation)

CPLErr GXFGetPosition (GXFHandle hGXF, double * pdfXOrigin, double * pdfYOrigin, double * pdfXPixelSize, double * pdfYPixelSize, double * pdfRotation)

void GXFClose (GXFHandle hGXF)