    			GDAL Data Model
    		        ===============

    This document attempts to describe the GDAL data model.  That is the
    types of information that a GDAL data store can contain, and their
    semantics.

    Dataset
    =======

    A dataset (represented by the GDALDataset class) is an assembly of
    related raster bands and some information common to them all.  In particular
    the dataset has a concept of the raster size (in pixels and lines) that
    applies to all the bands.  The dataset is also responsible for the
    georeferencing transform and coordinate system definition of all bands.  The
    dataset itself can also have associated metadata, a list of name/value
    pairs in string form.

    Note that the GDAL dataset, and raster band data model is loosely
    based on the OpenGIS Grid Coverages specification.

    Coordinate System
    -----------------

    Dataset coordinate systems are represented as OpenGIS Well Known Text
    strings.  This can contain:

     o An overall coordinate system name.
     o A geographic coordinate system name.
     o A datum identifier.
     o An ellipsoid name, semi-major axis, and inverse flattening.
     o A prime meridian name and offset from Greenwich.
     o A projection method type (ie. Transverse Mercator).
     o A list of projection parameters (ie. central_meridian).
     o A units name, and conversion factor to meters or radians.
     o Names and ordering for the axes.
     o Codes for most of the above in terms of predefined coordinate systems
       from authorities such as EPSG.

    For more information on OpenGIS WKT coordinate system definitions, and
    mechanisms to manipulate them, refer to the osr_tutorial document and/or the
    OGRSpatialReference class documentation.

    The coordinate system returned by GDALDataset::GetProjectionRef()
    describes the georeferenced coordinates implied by the affine georeferencing
    transform returned by GDALDataset::GetGeoTransform().  The coordinate
    system returned by GDALDataset::GetGCPProjection() describes the
    georeferenced coordinates of the GCPs returned by GDALDataset::GetGCPs().

    Note that a returned coordinate system strings of "" indicates nothing
    is known about the georeferencing coordinate system.

    Affine GeoTransform
    -------------------

    GDAL datasets have two ways of describing the relationship between
    raster positions (in pixel/line coordinates) and georeferenced coordinates.
    The first, and most commonly used is the affine transform (the other is
    GCPs).

    The affine transform consists of six coefficients returned by
    GDALDataset::GetGeoTransform() which map pixel/line coordinates into
    georeferenced space using the following relationship:

        Xgeo = GT(0) + Xpixel*GT(1) + Yline*GT(2)
        Ygeo = GT(3) + Xpixel*GT(4) + Yline*GT(5)

    In case of north up images, the GT(2) and GT(4) coefficients are zero, and
    the GT(1) is pixel width, and GT(5) is pixel height.  The (GT(0),GT(3))
    position is the top left corner of the top left pixel of the raster.

    GCPs
    ----

    A dataset can have a set of control points relating one or more positions
    on the raster to georeferenced coordinates.  All GCPs share a georeferencing
    coordinate system (returned by GDALDataset::GetGCPProjection()).  Each GCP
    (represented as the GDAL_GCP class) contains the following:

    typedef struct
    {
        char	*pszId;
        char	*pszInfo;
        double 	dfGCPPixel;
        double	dfGCPLine;
        double	dfGCPX;
        double	dfGCPY;
        double	dfGCPZ;
    } GDAL_GCP;

    The pszId string is intended to be a unique (and often, but not always
    numerical) identifier for the GCP within the set of GCPs on this dataset.
    The pszInfo is usually an empty string, but can contain any user defined
    text associated with the GCP.  Potentially this can also contain machine
    parsable information on GCP status though that isn't done at this time.

    The (Pixel,Line) position is the GCP location on the raster.  The (X,Y,Z)
    position is the associated georeferenced location with the Z often being
    zero.

    The GDAL data model does not imply a transformation mechanism that must
    be generated from the GCPs ... this is left to the application.  However
    1st to 5th order polynomials are common.

    Normally a dataset will contain either an affine geotransform, GCPs or
    neither.  It is uncommon to have both, and it is undefined which is
    authoritative.

    Metadata
    --------

    GDAL metadata is auxilary format and application specific textual data
    kept as a list of name/value pairs.  The names are required to be well
    behaved tokens (no spaces, or odd characters).  The values can be of
    any length, and contain anything except an embedded null (ASCII zero).

    The metadata handling system is well tuned to handling very large bodies
    of metadata.  Handling of more than 100K of metadata for a dataset is likely
    to lead to performance degredation.

    Over time there will be some well known names defined with established
    semantics; however, that has not occured at this time.

    Some formats will support generic (user defined) metadata, while other
    format drivers will map specific format fields to metadata names.  For
    instance the TIFF driver returns a few information tags as metadata
    including the date/time field which is returned as:

    TIFFTAG_DATETIME=1999:05:11 11:29:56

    Raster Band
    ===========

    A raster band is represented in GDAL with the GDALRasterBand class.  It
    represents a single raster band/channel/layer.  It does not necessarily
    represent a whole image.  For instance, a 24bit RGB image would normally
    be represented as a dataset with three bands, one for red, one for green
    and one for blue.

    A raster band has the following properties:

     o A width and height in pixels and lines.  This is the same as that
       defined for the dataset, if this is a full resolution band.

     o A datatype (GDALDataType).  One of Byte, UInt16, Int16, UInt32, Int32,
       Float32, Float64, and the complex types CInt16, CInt32, CFloat32, and
       CFloat64.

     o A block size.  This is a preferred (efficient) access chunk size.  For
       tiled images this will be one tile.  For scanline oriented images this will
       normally be one scanline.

     o A list of name/value pair metadata in the same format as the dataset,
       but of information that is potentially specific to this dataset.

     o An optional description string.

     o An optional list of category names (effectively class names in a
       thematic image).

     o An optional minimum and maximum value.

     o An optional offset and scale for transforming raster values into
       meaningful values (ie translate height to meters)

     o An optional raster unit name.  For instance, this might indicate linear
       units for elevation data.

     o A color interpretation for the band.  This is one of:
       - GCI_Undefined: the default, nothing is known.
       - GCI_GrayIndex: this is an independent grayscale image
       - GCI_PaletteIndex: this raster acts as an index into a color table
       - GCI_RedBand: this raster is the red portion of an RGB or RGBA image
       - GCI_GreenBand: this raster is the green portion of an RGB or RGBA image
       - GCI_BlueBand: this raster is the blue portion of an RGB or RGBA image
       - GCI_AlphaBand: this raster is the alpha portion of an RGBA image
       - GCI_HueBand: this raster is the hue of an HLS image
       - GCI_SaturationBand: this raster is the saturation of an HLS image
       - GCI_LightnessBand: this raster is the hue of an HLS image
       - GCI_CyanBand: this band is the cyan portion of a CMY or CMYK image
       - GCI_MagentaBand: this band is the magenta portion of a CMY or CMYK image
       - GCI_YellowBand: this band is the yellow portion of a CMY or CMYK image
       - GCI_BlackBand: this band is the black portion of a CMYK image.

     o A color table, described in more detail later.

     o Knowledge of reduced resolution overviews (pyramids) if available.

    Color Table
    -----------

    A color table conists of zero or more color entries described in C by the
    following structure:

    typedef struct
    {
        /- gray, red, cyan or hue -/
        short      c1;

        /- green, magenta, or lightness -/
        short      c2;

        /- blue, yellow, or saturation -/
        short      c3;

        /- alpha or blackband -/
        short      c4;
    } GDALColorEntry;

    The color table also has a palette interpretation value (GDALPaletteInterp)
    which is one of the following values, and indicates how the c1/c2/c3/c4 values
    of a color entry should be interpreted.

     o GPI_Gray: Use c1 as grayscale value.
     o GPI_RGB: Use c1 as red, c2 as green, c3 as blue and c4 as alpha.
     o GPI_CMYK: Use c1 as cyan, c2 as magenta, c3 as yellow and c4 as black.
     o GPI_HLS: Use c1 as hue, c2 as lightness, and c3 as saturation.

    To associate a color with a raster pixel, the pixel value is used as a
    subscript into the color table.  That means that the colors are always
    applied starting at zero and accending.  There is no provision for indicating
    a prescaling mechanism before looking up in the color table.

    Overviews
    ---------

    A band may have zero or more overviews.  Each overview is represented as
    a "free standing" GDALRasterBand.  The size (in pixels and lines) of the
    overview will be different than the underlying raster, but the geographic
    region covered by overviews is the same as the full resolution band.

    The overviews are used to display reduced resolution overviews more quickly
    than could be done by reading all the full resolution data and downsampling.

    Bands also have a HasArbitraryOverviews property which is TRUE if the
    raster can be read at any resolution efficiently but with no distinct
    overview levels.  This applies to some FFT encoded images, or images pulled
    through gateways (like OGDI) where downsampling can be done efficiently
    at the remote point.

Frank's Course Outline
OpenEV Help