Copyright 2006 Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License");
You may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"as is" basis, without warranties or conditions of any kind,
either express or implied. See the License for the specific
language governing permissions and limitations under the License.

$URL$
$Revision$
$Date$

KML Regionator:

What it is:

    The KML Regionator is a set of sample Python classes, algorithms and
    scripts that exemplify some methods for creating Region-based KML.

    The "placemarks.py" script inputs a large KML file of Point Placemarks
    ordered by importance and outputs a Region NetworkLink hierarchy of
    many small KML files of the Placemarks sorted by location.

    The "superoverlay.py" script inputs a north-up aligned image and emits
    a Region NetworkLink hierarchy of GroundOverlays or "SuperOverlay."

    If you enjoy hand-editing your XML (and KML), you view the command line
    as your most powerful tool, and you love Python, then you'll feel right
    at home.

    The intent of the liberal licensing of this software is to encourage
    to you to: 

    1. Use this software "as is" to generate your own Region KML,
       which you are free to distribute, and/or 

    2. Copy, modify, and incorporate this software in your own tools
       (commercial, open-source or other), and/or 

    3. Study this software to provide you with ideas to use in your
       own software and KML.

    We encourage your efforts to use or study this software in
    creating content-rich KML.


What it is NOT:

    This is not GUI-based, end-user-oriented production-quality software.
    Error checking and documentation are limited.  The KML generated may
    not be ideal under all circumstances.  The image handling features are
    rudimentary with respect to tile extraction, filtering, and compression.

    For the most up to date and authoritative KML documentation, please see:
    http://earth.google.com/kml/

    This tool does not exemplify the full universe of possibilities for
    generating Region-based KML, nor are all features -- of Regions in
    specific and KML in general -- shown or generated by this code.
    This is not a complete KML generation library, nor is it a
    complete KML-object model.

    We do not provide support for this software


Google Earth 4 (beta):

    The target of the generated KML is Google Earth 4 beta and
    KML 2.1 beta, both of which are subject to change without notice
    and hence the generated KML may or may not work in future releases
    of Google Earth 4.0 and KML 2.1 products.

    The KML generated will not work in Google Earth 3.

    For the latest version of Google Earth 4 (beta) please visit:

    http://earth.google.com/earth4.html


Contact info:

    For questions and comments, please visit the Google Earth Community
    (http://bbs.keyhole.com/), where you can post questions
    (and answers) about KML in the "KML Discussions" forum.


SuperOverlay support requires the following (not included):

    gdal 1.3.2 (www.gdal.org)
    Numeric 24.2 (numeric.scipy.org)


Installation:

    ./setup.py install

    See the following for information on installing in an
    alternate location:

    http://docs.python.org/inst/search-path.html

    Be sure to set PYTHONPATH accordingly.


Platforms:

    Linux, Mac OSX, Windows Cygwin


Tests:

    Run "sh testall.sh" in tests to verify proper installation.
    This test is not self-checking. The "test.kml" file references the
    KML generated by the test script such that you can view the result
    in Google Earth.


Scripts:

    A script invoked with no arguments prints a usage message.

    superoverlay.py - creates a SuperOverlay
    placemarks.py - creates a Region hierarchy of existing Placemarks
    insertregions.py - inserts a Region per Folder


Documentation:

    pydoc kml
    pydoc kml.regionator
    pydoc kml.regionhandler
    pydoc kml.superoverlay