Changeset 3612 for DPPP


Ignore:
Timestamp:
14/03/08 16:44:10 (11 years ago)
Author:
mkochan
Message:

Added Epydoc fields to comments.

Location:
DPPP/kml/csml2kml/python/csml2kml/csml2kml
Files:
7 edited

Legend:

Unmodified
Added
Removed
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/KML.py

    r3576 r3612  
     1''' 
     2Classes representing various KML elements. 
     3 
     4The official Google KML reference is located at  
     5U{http://code.google.com/apis/kml/documentation/kml_tags_21.html}. 
     6''' 
     7 
    18import os 
    29import sys 
     
    714class KMLElement: 
    815    ''' 
    9     Abstract class, representing any element of a KML document -- i.e. anything contained *within* 
    10     the <kml:Document> element. 
     16    Abstract class, represents a KML element. Each C{KMLElement} can be I{built} using the C{build} method 
     17    into an actual C{cElement.Element} object, which is the actual XML.  
    1118    ''' 
    1219 
    1320    def build(self): 
    1421        ''' 
    15         It is required that each KMLElement instance is able to build() itself into an ElementTree.Element 
    16         instance of KML, which it represents. 
     22        Build this object, which is a representation of a KML element, 
     23        and all of its contained objects (if any), I{directly} into a XML element. 
     24        @rtype: C{cElement.Element} 
    1725        ''' 
    1826        raise NotImplementedError("Abstract method, to be overriden by child classes") 
    1927 
    20 class KMLDocument: 
     28class KMLDocument(KMLElement): 
    2129    ''' 
    2230    Wraps around a whole KML document and makes it possible to save it to a file directly. 
    23     Represent the <kml:Document>, so that the method build() builds the kml:Document element, 
    24     but also contains the method save() that allows saving that to a file, wrapped within the <kml> header. 
     31    Represent the I{<kml:Document>}, so that the method C{build} builds the kml:Document element, 
     32    but also contains the method C{save} that allows saving the XML to a file, wrapped within the <kml> header. 
    2533    ''' 
    2634 
     
    5058    def save(self, outputFilename): 
    5159        ''' 
    52         Save the document to file <code>outputFilename</code> (full path). 
     60        Save the document to file C{outputFilename} (full path), wrapped in the I{<kml>} element. 
     61        @param outputFilename: Name of the destination file. 
     62        If the suffix is "kml" (in any case), the saved file will be an unpacked KML file. 
     63        If the suffix is "kmz" (in any case), the saved file will be a ZIP archive file, 
     64        containing the KML in a file named 'doc.kml'. 
    5365        ''' 
    5466 
     
    126138class KMLStyle(KMLElement): 
    127139    ''' 
    128     Represents the <kml:Style> tag. 
     140    Represents the I{<kml:Style>} tag. 
     141 
     142    KML styles are used to extend behaviour of various KML elements. In particular, they can be used to define: 
     143      - images used for drawing KML placemarks 
     144      - defining HTML templates for placemark balloons 
     145      - defining list types for KML folders 
     146    Any KML element can have exactly one style associated with it. 
     147    @ivar id: Style identifier 
     148    @type id: C{str} 
     149    @ivar iconURL: Can contain URL for an icon image to be drawn on spot of a placemark; 
     150    to be associated with C{KMLPlacemark} objects. 
     151    @type iconURL: C{str} 
     152    @ivar balloonTemplate: Can contain a HTML template with variables that are substituted during build 
     153    using from C{KMLPlacemark.data} attributes; 
     154    to be associated with C{KMLPlacemark} objects. 
     155    @type balloonTemplate: C{str} 
     156    @ivar listItemType: Can contain a string designating listing mode for a KML folder; 
     157    to be associated with C{KMLFolder} objects; 
     158    permitted values are: "C{check}", "C{checkOffOnly}", "C{checkHideChildren}", "C{radioFolder}". 
     159    @type listItemType: C{str} 
    129160    ''' 
    130161 
     
    134165        self.balloonTemplate = balloonTemplate 
    135166        if listItemType: 
    136             allowedValues =  ['check', 'checkOffOnly', 'checkHideChildren', 'radioFolder'] 
     167            allowedValues = ['check', 'checkOffOnly', 'checkHideChildren', 'radioFolder'] 
    137168            if not listItemType in allowedValues: 
    138169                raise ValueError('listItemType not among allowed values: ' + str(allowedValues)) 
     
    168199                                  balloonTemplate = ''): 
    169200    ''' 
    170     A factory method defined for convenience. Creates a style readily usable for adding styles to KML placemarks. 
     201    A factory method defined for convenience. Creates a "default placemark style". 
     202    @rtype: C{KMLStyle} 
    171203    ''' 
    172204    return KMLStyle(id, iconURL, balloonTemplate) 
     
    174206class KMLPlacemark(KMLElement): 
    175207    ''' 
    176     Represents the <kml:Placemark> tag. 
     208    Represents the I{<kml:Placemark>} tag. 
     209    @ivar id: Placemark identifier 
     210    @type id: C{str} 
     211    @ivar name: Human-readable name 
     212    @type name: C{str} 
     213    @ivar lon: Longitude 
     214    @type lon: C{float} 
     215    @ivar lat: Latitude 
     216    @type lat: C{float} 
     217    @ivar styleID: Style identifier (see C{KMLStyle.id})  
     218    @type styleID: C{str} 
     219    @ivar data: A dictionary containing instance-specific data items which are to be substituted 
     220    for in the balloon template by the values defined by C{self.data}. 
     221    @type data: C{dict} 
     222    @ivar visible: Determines whether the placemark is visible (ie. checked) initially when loaded 
     223    @type visible: C{bool} 
    177224    ''' 
    178225     
     
    222269class KMLFolder(KMLElement): 
    223270    ''' 
    224     Represents the <kml:Folder> tag. 
     271    Represents the I{<kml:Folder>} tag. 
     272    @ivar name: Human-readable folder name 
     273    @type name: C{str} 
     274    @ivar description: Human-readable detailed description of folder contents (appears greyish below the name). 
     275    @type description: C{str} 
     276    @ivar children: A list of embedded elements. 
     277    @type children: C{KMLElement list} 
     278    @ivar styleID: Style identifier (see C{KMLStyle.id})  
     279    @type styleID: C{str} 
     280    @ivar region: A region associated with this folder. 
     281    @type region: C{KMLRegion} 
     282    @ivar opened: Determines whether the placemark is opened (that is, listed) when initially loaded 
     283    @type opened: C{bool} 
     284    @ivar visible: Determines whether the placemark is visible (that is, checked) when initially loaded 
     285    @type visible: C{bool} 
    225286    ''' 
    226287 
     
    261322class KMLRegion(KMLElement): 
    262323    ''' 
    263     Represents the <kml:Region> tag. 
     324    Represents the I{<kml:Region>} tag. 
     325 
     326    Elements which have a region associated with them will only be rendered (even if set as visible) 
     327    when their region is at least {minLodPixels} large and at most {maxLodPixels} large on the screen. 
     328    @ivar west: Bounding box coordinate 
     329    @type west: C{float} 
     330    @ivar south: Bounding box coordinate 
     331    @type south: C{float} 
     332    @ivar east: Bounding box coordinate 
     333    @type east: C{float} 
     334    @ivar north: Bounding box coordinate 
     335    @type north: C{float} 
    264336    ''' 
    265337     
     
    289361 
    290362class KMLGroundOverlay(KMLElement): 
    291     '''Represents the <kml:GroundOverlay> tag.''' 
     363    ''' 
     364    Represents the I{<kml:GroundOverlay>} tag. 
     365    @ivar name: Human-readable name 
     366    @type name: C{str} 
     367    @ivar sourceUrl: URL of the image to be superimposed on the ground 
     368    @type sourceUrl: C{str} 
     369    @ivar timespanStart: Start of validity period for the overlay. 
     370    @type timespanStart: C{pylab.dates.datetime.datetime} 
     371    @ivar timespanEnd: End of validity period for the overlay. 
     372    @type timespanEnd: C{pylab.dates.datetime.datetime} 
     373    @ivar west: Bounding box coordinate 
     374    @type west: C{float} 
     375    @ivar south: Bounding box coordinate 
     376    @type south: C{float} 
     377    @ivar east: Bounding box coordinate 
     378    @type east: C{float} 
     379    @ivar north: Bounding box coordinate 
     380    @type north: C{float} 
     381    ''' 
    292382 
    293383    def __init__(self, name, sourceUrl, timespanStart, timespanEnd, west, south, east, north, visible = True): 
     
    331421 
    332422class KMLNetworkLink(KMLElement): 
     423    ''' 
     424    Represents a I{<kml:NetworkLink>} element.  
     425 
     426    Such an element is listed as a folder, but is only loaded from a fetched KML file when clicked at. 
     427    @ivar name: Network link name. 
     428    @type name: C{str} 
     429    @ivar url: URL from which to fetch the link contents. 
     430    @type url: C{str} 
     431    @ivar description: Human-readable description of network link contents (appears greyish below the name). 
     432    @type description: C{str} 
     433    @ivar styleID: Style identifier (see C{KMLStyle.id})  
     434    @type styleID: C{str} 
     435    @ivar visible: Determines whether the placemark is visible (that is, checked) when initially loaded 
     436    @type visible: C{bool} 
     437    ''' 
    333438 
    334439    def __init__(self, name, url, description = None, styleID = None, visible = True): 
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/QuadTree.py

    r3439 r3612  
    11''' 
    2 Classes and functions for producing geographic quat trees, i.e. trees which enable quadric recursive space splitting. 
     2Classes and functions for storing locations in quadric trees (representations of quadric splitting of space). 
     3 
     4It is possible to split locations in longitude-latitude space by recursive splitting regions (bounding boxes) 
     5into 4 smaller regions (the NE, NW, SW and SE region) until each low-level box does not contain 
     6a defined maximum of locations. 
     7 
     8The intended use for quadric splitting here is to allow storing I{<np:Station>} elements into a hierarchy 
     9of KML folders with associated KML regions, thereby making them to get rendered only for closer zooms 
     10to the ground. 
    311''' 
    412 
     
    1018class Location: 
    1119    ''' 
    12     Represents a geographic location (lon, lat) which has some object, obj, associated with it 
     20    Represents a geographic location (C{lon}, C{lat}) with an associated object, C{obj}. 
     21    @ivar lon: The location longitute. 
     22    @type lon: C{float} 
     23    @ivar lat: The location latitude. 
     24    @type lat: C{float} 
     25    @ivar obj: The associated object. 
     26    @type obj: C{instance} 
    1327    ''' 
    1428    def __init__(self, lon, lat, obj): 
     
    1933 
    2034class Tree: 
    21     ''' 
    22     Abstract class, represents a tree of regions/locations. The tree can be converted 
    23     directly to a KML document which contains station locations using KML regions. 
    24     ''' 
     35    '''Abstract class, represents a quadric tree of regions/locations.''' 
    2536    pass 
    2637 
    2738class Leaf(Tree): 
     39    '''Abstract class, represents all leaves in a quadric tree.''' 
    2840    pass 
    2941 
     
    3850class LocLeaf(Leaf): 
    3951    ''' 
    40     A tree leaf containing locations, i.e. Location objects. 
     52    A tree leaf containing locations (C{Location} objects). 
    4153    ''' 
    4254    def __init__(self, locations, bbox): 
     
    5264class Node(Tree): 
    5365    ''' 
    54     A tree node which contains children, being themselves Tree objects. 
     66    A tree node which contains children (C{Tree} objects). 
    5567    ''' 
    5668    def __init__(self, children, bbox): 
     
    6678class BBox: 
    6779    ''' 
    68     Represents a bounding box, i.e. a geographical 2D region (considering longitute & latitude only, 
    69     ignoring altitude). Contains 4 methods for splitting the region into its SW, SE, NW, NE parts 
    70     (i.e. quadratic splitting). 
     80    Represents  a geographical 2D region. 
     81    Contains 4 methods for splitting the region quadrically (into its SW, SE, NW, NE parts). 
    7182    ''' 
    7283 
     
    7990        return 'BBox(lon:%s--%s,lat:%s--%s)' % (self.west, self.east, self.south, self.north) 
    8091    def lon_centre(self): 
     92        ''' 
     93        Get the central longitude for the bbox. 
     94        @rtype: C{int} 
     95        ''' 
    8196        return (self.west + self.east) / 2 
    8297    def lat_centre(self): 
     98        ''' 
     99        Get the central latitude for the bbox. 
     100        @rtype: C{int} 
     101        ''' 
    83102        return (self.south + self.north) / 2 
    84103    def sw(self): 
     104        ''' 
     105        Get the SW quarter of the bounding box. 
     106        @rtype: C{BBox} 
     107        ''' 
    85108        return BBox(self.west, self.south, self.lon_centre(), self.lat_centre()) 
    86109    def se(self): 
     110        ''' 
     111        Get the SE quarter of the bounding box. 
     112        @rtype: C{BBox} 
     113        ''' 
    87114        return BBox(self.lon_centre(), self.south, self.east, self.lat_centre()) 
    88115    def nw(self): 
     116        ''' 
     117        Get the NW quarter of the bounding box. 
     118        @rtype: C{BBox} 
     119        ''' 
    89120        return BBox(self.west, self.lat_centre(), self.lon_centre(), self.north) 
    90121    def ne(self): 
     122        ''' 
     123        Get the NE quarter of the bounding box. 
     124        @rtype: C{BBox} 
     125        ''' 
    91126        return BBox(self.lon_centre(), self.lat_centre(), self.east, self.north) 
    92127 
     
    95130def build_quadtree(l,bbox=BBox(-180.,-90.,180.,90.),max_per_region=16): 
    96131    ''' 
    97     Description:               Performs quad-tree segmentation of space, to store (station) locations 
    98                                in a tree that contains locations in a hierarchy of smaller and smaller segments/nodes, 
    99                                each smaller node produced by splitting the space into 4 sub-spaces. 
    100      
    101     Input:               l ... List of (station) locations, i.e. of Location objects 
    102                       bbox ... A BBox object determining the main bounding box enwrapping 
    103                                all possible time boxes, i.e. the one from which to start dividing. 
    104                                Supply BBox(-180.,-90.,180.,90.) to use whole globe. 
    105             max_per_region ... Maximum number of locations to be contained in a lowest-level region 
    106                                (i.e. in a LocLeaf object). This determines the depth of the resultant 
    107                                tree. 
    108  
    109     Output:                    The quad-tree. 
     132    Performs quadric splitting of space. 
     133    @param l: The locations to be splitted 
     134    @type l: C{Location list} 
     135    @param bbox: The region to split in this recursive iteration (using the default gives the whole globe) 
     136    @type bbox: C{BBox} 
     137    @param max_per_region: Maximum number of locations to be contained in a lowest-level region 
     138    (in a C{LocLeaf} object). This influences the depth of the resultant tree. 
     139    @return: The quad-tree. 
     140    @rtype: C{QuadTree} 
    110141    ''' 
    111142    if len(l) == 0: 
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/Station.py

    r3600 r3612  
     1''' 
     2Classes for work with I{<np:Station>}'s. 
     3''' 
     4 
    15from cElementTree import XML 
    26 
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/StationConvertor.py

    r3598 r3612  
     1''' 
     2Contains class C{StationConvertor}. 
     3''' 
     4 
    15from cElementTree import ElementTree, Element, SubElement, XML 
    26from pylab import * 
     
    5256 
    5357    def _npStationToKmlPlacemark(self, npStation): 
    54         '''Converts a C{Station.NPStation} object into it's C{KML.KMLPlacemark} representation''' 
     58        ''' 
     59        Converts a C{Station.NPStation} object into it's C{KML.KMLPlacemark} representation 
     60        @rtype: C{KML.KMLPlacemark} 
     61        ''' 
    5562        return KMLPlacemark(npStation.id, npStation.desc, npStation.lon, npStation.lat, 
    5663                            styleID = self.placemarkKmlStyle.id, data = self.stationData 
     
    6572        @param npStations: A list of stations to be contained in the hierarchy. 
    6673        @type npStations: List of C{Station.NPStation} objects. 
    67         @return: A C{KML.KMLDocument} object. 
     74        @rtype: C{KML.KMLDocument} 
    6875        ''' 
    6976        for npStation in npStations: 
     
    7986        @param npStations: A list of stations to be contained in the hierarchy. 
    8087        @type npStations: List of C{Station.NPStation} objects. 
    81         @return: A C{KML.KMLDocument} object. 
     88        @rtype: C{KML.KMLDocument} 
    8289        ''' 
    8390 
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/WMSLayer.py

    r3603 r3612  
     1''' 
     2Classes for work with I{<wms:Layer>}'s. 
     3''' 
     4 
    15import os 
    26import re 
     
    96100          - Each KML file encoding a I{bottom WMS layer} contains views of the data in the bottom layer, 
    97101            with the views specified by the C{viewTypes} parameter. 
    98         @param wmsRequestConfigElement: The <WMSRequest> element from the config file (containing information 
     102        @param wmsRequestConfigElement: The I{<WMSRequest>} element from the config file (containing information 
    99103        about how WMS requests are to be made, e.g. which server to use, what resolution to use, etc.) 
    100104        @type wmsRequestConfigElement: C{cElementTree.Element} 
     
    107111        @param parentDirUrl: The URL from which the output will be served, corresponding to the root output directory. 
    108112        @type parentDirUrl: C{str} 
    109         @return: A C{KML.KMLNetworkLink} object representing a I{<kml:NetworkLink>} to the uppermost-leve created KMZ file 
     113        @return: An object representing a I{<kml:NetworkLink>} to the uppermost-leve created KMZ file 
     114        @rtype: C{KML.KMLNetworkLink} 
    110115        ''' 
    111116 
     
    210215        @param parentDirUrl: (ignored) 
    211216        @type parentDirUrl: C{str} 
    212         @return: A C{KML.KMLFolder} object containing individual views of the layers (as sub-folders). 
     217        @return: An object containing individual views of the layers (as sub-folders). 
     218        @rtype: C{KML.KMLFolder} 
    213219        ''' 
    214220         
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/WMSLayerConvertor.py

    r3595 r3612  
     1''' 
     2Contains the class C{WMSLayerConvertor}. 
     3''' 
     4 
    15from WMSLayer import * 
    26 
    37class WMSLayerConvertor: 
    4      
     8    ''' 
     9    Encapsulates conversion from WMS layers to a KML file hierarchy. 
     10    ''' 
     11 
    512    def __init__(self, topWmsLayer, wmsRequestConfigElement, baseKmlOutputDirectory, baseKmlOutputUrl): 
     13        ''' 
     14        The constructor. 
     15        @param topWmsLayer: The top WMS layer to be converted. 
     16        @type topWmsLayer: C{WMSLayer.WMSLayer} 
     17        @param wmsRequestConfigElement: The I{<WMSRequest>} element from the config file (containing information 
     18        about how WMS requests are to be made, e.g. which server to use, what resolution to use, etc.) 
     19        @type wmsRequestConfigElement: C{cElementTree.Element} 
     20        @param baseKmlOutputDirectory: A directory to be used as the root of the output. 
     21        The KMZ file corresponding to the uppermost layer will be contained directly in this directory. 
     22        @type baseKmlOutputDirectory: C{str} 
     23        @param baseKmlOutputUrl: The URL from which the output will be served, corresponding to the root output directory. 
     24        @type baseKmlOutputUrl: C{str} 
     25        ''' 
    626        self.topWmsLayer = topWmsLayer 
    727        self.wmsRequestConfigElement = wmsRequestConfigElement 
     
    1030         
    1131    def convert(self): 
     32        ''' 
     33        Perform the conversion. 
     34 
     35        This will create a hierarchy of KMZ files embedded in directories. 
     36        Each KMZ files encodes a single I{<wms:Layer>} element, as follows: 
     37          - Each KMZ file encoding a {non-bottom WMS layer} contains a number of I{<kml:NetworkLink>}'s mapping 
     38            to the KMZ files in a lower directory. 
     39            The I{<kml:NetworkLink>} contains an absolute URL of the target on the machine from the KMZ file 
     40            is being served. 
     41          - Each KML file encoding a I{bottom WMS layer} contains views of the data in the bottom layer, 
     42            with the views specified by the C{viewTypes} parameter. 
     43 
     44        The convertor uses the following 3 types of views, as defined in the C{WMSLayer} module: 
     45        C{ViewWholeTimecourse}, C{ViewSplittedByMonth}, C{ViewSplittedByPeriod}. 
     46        However, more views can be created (by extending {WMSLayer.View}) and added later. 
     47        ''' 
    1248        viewTypes = [ViewWholeTimecourse, ViewSplittedByMonth, ViewSplittedByPeriod] 
    1349        self.topWmsLayer.toKML(self.wmsRequestConfigElement, viewTypes, self.baseKmlOutputDirectory, self.baseKmlOutputUrl) 
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/utils.py

    r3464 r3612  
     1''' 
     2Utility/convenience functions. 
     3''' 
     4 
    15import urllib2 
    26 
     
    59    Read data from an URL. 
    610    @param url: The URL. 
    7     @return:    The returned data as a string, or None on retrieval error. 
     11    @type url: C{str} 
     12    @return: The returned data as a string, or C{None} on retrieval error. 
     13    @rtype: C{str} 
    814    ''' 
    915    content = None 
     
    2026            pass                             # f uninitialised, so no need to close it 
    2127    return content 
    22  
    23 def toDegreesMinutesSeconds(val): 
    24     ''' 
    25     Determine how many integer degrees, minutes, seconds, and float parts of seconds there are 
    26     in an angle value given in float degrees. 
    27     @param val: An angle in float degrees. 
    28     @return:    A tuple containing (int degrees, int minutes, int seconds, float remainder in seconds). 
    29                 The float remainder is a value between 0. (inclusive) and 1. (exclusive). 
    30     ''' 
    31     if val >= 0:  
    32         sign = 1 
    33     else:  
    34         sign = -1 
    35     val = abs(val) 
    36     degrees = int(val) 
    37     decim = val % 1. 
    38     minute = 1/60. 
    39     second = 1/3600. 
    40     minutes = int(decim / minute) 
    41     remainder = decim % minute 
    42     seconds = int(remainder / second) 
    43     remainder = remainder % second 
    44     remainderInSeconds = remainder / second 
    45     return (sign * degrees, minutes, seconds, remainderInSeconds) 
    46  
    47 def loadConfigElement(configFilename, basePath): 
    48     tree = ElementTree() 
    49     root = tree.parse(configFilename) 
    50     return root.find(basePath) 
Note: See TracChangeset for help on using the changeset viewer.