			The BMGGeoTIFF API Manual

			       Scott Heiman
			   scottheiman@cox.net
		   http:\\members.cox.net\scottheiman\

INTRODUCTION
------------

GeoTIFF images are "extended" TIFF images that contain information that can be 
used to georeference satellite images or digital maps.  The BMGGeoTIFF project
creates a DLL that encapsulates the GeoTIFF library and exports data and 
imagery that can be used to manipulate GeoTIFF images.  This document describes 
the BMGGeoTIFF API.

OBLIGATORY LEGAL RAMBLINGS
--------------------------

  BMGGeoTIFF is Copyright 2001 M. Scott Heiman
  All Rights Reserved
  libTIFF is Copyright Sam Leffler and Silicon Graphics International
  zLib Copyright (C) 1995-1998 Jean-loup Gailly.
  GeoTIFF is Copyright (c) 1999, Frank Warmerdam
  libPROJ (used by GeoTIFF) is Copytight (c) 2000, Frank Warmerdam

 You may use the software for any purpose you see fit. You may modify
 it, incorporate it in a commercial application, use it for school,
 even turn it in as homework. You must keep the Copyright in the
 header and source files. This software is not in the "Public Domain".  
 You may use this software at your own risk. I have made a reasonable 
 effort to verify that this software works in the manner I expect it to; 
 however,...

 THE MATERIAL EMBODIED ON THIS SOFTWARE IS PROVIDED TO YOU "AS-IS" AND
 WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING
 WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A
 PARTICULAR PURPOSE. IN NO EVENT SHALL MICHAEL S. HEIMAN BE LIABLE TO
 YOU OR ANYONE ELSE FOR ANY DIRECT, SPECIAL, INCIDENTAL, INDIRECT OR
 CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER, INCLUDING
 WITHOUT LIMITATION, LOSS OF PROFIT, LOSS OF USE, SAVINGS OR REVENUE,
 OR THE CLAIMS OF THIRD PARTIES, WHETHER OR NOT MICHAEL S. HEIMAN HAS
 BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSS, HOWEVER CAUSED AND ON
 ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
 POSSESSION, USE OR PERFORMANCE OF THIS SOFTWARE.

OVERVIEW
--------

GeoTIFF images are usually digitized maps or satellite images that have
been gereferenced to the earth.  A GeoTIFF image contains the information 
needed to map each pixel in the image to a point on the earth.  The 
BMGGeoTIFF library extracts that information along with the image so that it 
can be used in a GIS type of application.

The BMGGeoTIFF is designed to work with either the BMGLib library or the
BMGLibTIFF library.  The BMGGeoTIFF makes use of the BMGLib and BMGLibTIFF 
functions.  These functions are described in the BMGLibAPI.txt file located in 
the "Projects\BMGLib\BMGLib_DLL" folder.  The BMGGeoTIFF API adds additional 
functions and data structures that are unique to GeoTIFFs.  This document 
describes the data structures and functions that are unique to the BMGGeoTIFF
library.

DATA STRUCTURES
---------------

The BMGImageStruct, defined in the BMGLibAPI.txt file is used to store image 
information for GeoTIFFs.

The GeoTIFFInfoStruct contains the additinal information that is needed to use
GeoTIFFs.  The GeoTIFFInfoStruct is defined as:

struct GeoTIFFInfoStruct
{
    TiffCompression compression;
    TiffPhotometric photometric;
    TiffOrientation orientation;
    unsigned short predictor;
    double pixel_origin[2];
    double image_origin[2];
    double map_resolution[2];
    GTIFDefn defn;
};

The compression, photometric, orientation, and predictor parameters are 
identical to the parameters defined in the TIFFInfoStruct defined in the 
BMGLibAPI.txt file.

The defn structure is defined by the GeoTIFF library.  The variables contained
in this structure are defined in the GeoTIFF documentation.

image_origin is the earth referenced coordinates of the upper-left corner of the
image.  These coordinates can be latitude and longitude or the "easting" and
"northing" coordinates.  The units are defined by data contained in the defn
structure.

pixel_origin defines the pixel location that image_origin is referenced to.  
Typically, it is (0,0).

map_resolution contains the horizontal and vertical spacing of each pixel.  
The spacing is typically linear distance.  For example, if map_resolution =
(5,5), then each pixel covers a 5x5 meter area on the ground.  The units are
defined by the defn structure.

The pixel_origin, image_origin, and map_resolution can be used to map a pixel
to a location on the earth.  The following equations can be used to map (x,y) 
pixel location to an easting and a northing coordinate (UTM coordinates) .

int dx = x - pixel_origin[0];
int dy = y - pixel_origin[1];
double east  = image_origin[0] + dx * map_resolution[0];
double north = image_origin[1] - dy * map_resolution[1];

FUNCTIONS
---------

The BMGGeoTIFF DLL exports 4 additional functions that are unique to GeoTIFFs.
These functions are:

BMGError SaveBitmapToGeoTIFFile( HBITMAP hBitmap, 
                                 const char *filename, 
                                 struct GeoTIFFInfoStruct *info );

HBITMAP CreateBitmapFromGeoTIFFile( const char *filename,
                                    struct GeoTIFFInfoStruct *info,
                                    int blend );

BMGError ReadGeoTIFF( const char *filename,
                      struct BMGImageStruct *img,
                      struct GeoTIFFInfoStruct *info );

BMGError WriteGeoTIFF( const char *filename,
                       struct BMGImageStruct img,
                       struct GeoTIFFInfoStruct *info );


SaveBitmapToGeoTIFF saves the contents of an HBITMAP to a GeoTIFF file.  It 
will return BMG_OK if successfull, or an error code if a failure occured.

CreateBitmapFromGeoTIFFile will create an HBITMAP from a GeoTIFF file.  It will
return a valid HBITMAP if successfull, or NULL if an error occurred.  Use 
GetLastBMGError to determine what type of error occurred.

ReadGeoTIFF will store the contents of a GeoTIFF file into a BMGImageStruct.  
It will return BMG_OK if successfull, or an error code if an error occurred.

WriteGeoTIFF will save the contents of a BMGImageStruct into a GeoTIFF file. It
will return BMG_OK if successfull, or an error code if an error occurred.

The parameters for all of the functions are:
hBitmap  - HBITMAP to be saved to a file
filename - input/output file.  Must have TIF extension.
info     - pointer to a GeoTIFFInfoStruct.  MUST NOT BE NULL.
blend    - blend flag.  Set to 1 if you want a 32-BPP image to be blended with
           a bland background color.
img      - A BMGImageStruct that a) contains the data to be saved to a file 
           (WriteGeoTIFF) or b) will contain the data read from a file 
           (ReadGeoTIFF).

BUILDING BMGGEOTIFF
-------------------

You must build either BMGlib or BMGLibTIFF before building the BMGGeoTIFF DLL.
BMGGeoTIFF links with the import libraries created by those projects.

Borland C++ Builder (v5) and Microsoft Visual C++ (v6) project files have been 
included that will build two versions of the DLL.  The first version links with
the BMGLib DLL, and the second version links with the BMGLibTIFF DLL.  If your 
project does not need to support the other image file formats supported by 
BMGLib then you can use the second version.  The MS projects file will build 
both versions of the DLL.  For Borland, use the BMGGeoTIFF.bpr file to build 
the version that uses BMGLib.  Use the BMGGeoTIFFsa.bpr file to build the 
version that uses BMGLib.  Both BMGGeoTIFF.bpr and BMGGeoTIFFsa.bpr create a 
DLL named BMGGeoTIFF.dll.

USING BMGGEOTIFF
----------------

You must include the BMGGeoTIFF.h file in any module that uses the 
GeoTIFFInfoStruct or any of the functions.  Your include path should contain
"c:\projects\BMGLib\BMGLib_DLL", "c:\projects\BMGLib\BMGGeoTIFF_DLL", and
"c:\projects\BMGlib\libgeotiff114".  You must link the BMGGeoTIFF.lib file with
your project.  If you built the BMGGeoTIFF DLL with BMGLib, then you must link 
BMGLib.lib with your project.  If you built the version that uses BMGLibTIFF,
then you must link BMGLibTIFF.lib with your project.  The BMGGeoTIFF, BMGLib,
and BMGLibTIFF DLLs must be in your path.  Projects that use the BMGLibTIFF DLL
must also define _BMG_LIBTIFF_STANDALONE.

COMMENTS
--------

The GeoTIFF and PROJ libraries are included with this project.  Minor 
modifications were made to the source code to make it compile and link with
the Borland and Microsoft compilers.  The original source code can be obtained
from http://www.remotesensing.org.  DO NOT OVERWRITE MY CODE WITH THE CODE YOU
OBTAIN FROM REMOTESENSING.ORG.  

Enjoy...
Scott Heiman
1 February 2003
