Changeset 3600 for DPPP


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

Added comments to WMSLayer.py.

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

Legend:

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

    r3598 r3600  
    55class NPStation: 
    66    ''' 
    7     Represents a ground meteorological station, identified by C{id}, with description C{desc}, located at (C{lon},C{lat}), 
    8     and containing CSML features with identifiers C{csmlFeatureIds}. 
     7    Represents a ground meteorological station, identified by C{id}, with description C{desc}, 
     8    located at (C{lon},C{lat}), and containing CSML features with identifiers C{csmlFeatureIds}. 
    99    ''' 
    1010 
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/WMSLayer.py

    r3595 r3600  
    44from KML import * 
    55 
    6 wmsXmlNamespace = 'http://www.opengis.net/wms' 
     6wmsXmlNamespace = 'http://www.opengis.net/wms'  # a XML namespace in which the <wms:Layer> element is defined 
    77 
    88class BBox: 
     9    ''' 
     10    A geographic rectangular bounding box, bounding by longitude and latitude (but not altitude). 
     11    ''' 
    912    def __init__(self, west, south, east, north): 
     13        ''' 
     14        @type west: int 
     15        @type south: int 
     16        @type east: int 
     17        @type north: int 
     18        ''' 
    1019        self.west = west; self.east = east 
    1120        self.south = south; self.north = north 
    1221    def __repr__(self): 
     22        ''' 
     23        Print out the bounding box in a WMS query format (e.g.: '-180,-90,180,90') 
     24        ''' 
    1325        return str(self.west) + ',' + str(self.south) + ',' + str(self.east) + ',' + str(self.north) 
    1426 
    1527def wmsLayerFactory(layerElement, parentBBox = None): 
    1628    ''' 
    17     [DOC] 
     29    A factory function for generating new WMSLayer objects. 
     30    @param layerElement: A I{<wms:Layer>} element containing the top layer of a hierarchy of WMS layers. 
     31    @type layerElement: C{cElementTree.Element} 
     32    @param parentBBox: Bounding box of the parent layer. Leave C{None} (used by the function in recursive calls). 
     33    @type parentBBox: C{BBox} 
    1834    ''' 
    1935    name = layerElement.find('{%s}Name' % wmsXmlNamespace).text 
     
    4965class WMSLayer: 
    5066    ''' 
    51     [DOC] 
     67    A representation of the I{<wms:Layer>} element, which is normally contained within a I{<wms:Capabilities>} element 
     68    (see C{WMSCapabilities}). 
     69    However, bottom-layer I{<wms:Layer>} elements are represented by the C{BottomWMSLayer} objects, 
     70    with overriden behaviour. 
     71    @ivar name: Name of the layer 
     72    @ivar title: Title of the layer (more human readable than name) 
     73    @ivar abstract: Abstract of the layer (explanation of underlying data) 
     74    @ivar bbox: A C{BBox} of the layer 
     75    @ivar childen: A list of C{WMSLayer} objects contained within the WMS layer 
    5276    ''' 
    5377 
     
    6286        return str(vars(self)) 
    6387 
    64     def parseXML(self, layerElement): 
    65         raise NotImplementedError('Use the wmsLayerFactory() function instead.') 
     88    #def parseXML(self, layerElement): 
     89    #    ''' 
     90    #    Deprecated. 
     91    #    ''' 
     92    #    raise NotImplementedError('Use the wmsLayerFactory() function instead.') 
    6693 
    6794    def toKML(self, wmsRequestConfigElement, viewTypes, parentDir, parentDirUrl): 
    68  
    69         title_ = self.title.replace(' ', '_').replace('/', '_').replace('\\', '_')  # self.title "underscored" 
    70  
     95        ''' 
     96        Export the non-bottom layer to KML. This creates a hierarchy of KMZ files embedded in directories. 
     97        Each KMZ files encodes a single I{<wms:Layer>} element, as follows: 
     98          - Each KMZ file encoding a {non-bottom WMS layer} contains a number of I{<kml:NetworkLink>}'s mapping 
     99            to the KMZ files in a lower directory. 
     100            The I{<kml:NetworkLink>} contains an absolute URL of the target on the machine from the KMZ file 
     101            is being served. 
     102          - Each KML file encoding a I{bottom WMS layer} contains views of the data in the bottom layer, 
     103            with the views specified by the C{viewTypes} parameter. 
     104        @param wmsRequestConfigElement: The <WMSRequest> element from the config file (containing information 
     105        about how WMS requests are to be made, e.g. which server to use, what resolution to use, etc.) 
     106        @type wmsRequestConfigElement: C{cElementTree.Element} 
     107        @param viewTypes: A list of objects descended from C{View}, which determine how the visible layer data is to be 
     108        viewed. 
     109        @type viewTypes: C{View} list 
     110        @param parentDir: A directory to be used as the root of the output. The KMZ file corresponding to the uppermost 
     111        layer will be contained directly in this directory. 
     112        @type parentDir: C{str} 
     113        @param parentDirUrl: The URL from which the output will be served, corresponding to the root output directory. 
     114        @type parentDirUrl: C{str} 
     115        @return: A C{KML.KMLNetworkLink} object representing a I{<kml:NetworkLink>} to the uppermost-leve created KMZ file 
     116        ''' 
     117 
     118        # Create an "underscored" version of the title, in which all spaces, slashes, and backslashes 
     119        # are replaced with underscores. 
     120        title_ = self.title.replace(' ', '_').replace('/', '_').replace('\\', '_') 
     121 
     122        # Determine a full directory path and filename of the resulting KMZ file. Also determine thier corresponding URLs. 
    71123        dir = parentDir + '/' + title_ 
    72124        dirUrl = parentDirUrl + '/' + title_ 
     
    74126        fileUrl = dirUrl + '.kmz' 
    75127 
    76         # create directory dir 
     128        # Create the target directory. 
    77129        os.mkdir(dir) 
    78130        print 'Created directory "%s".' % dir 
    79131 
     132        # Create a representation of an empty KML document. 
    80133        kmlDocument = KMLDocument(self.title, []) 
     134 
     135        # Add each embedded layer into the document. 
    81136        for childWmsLayer in self.children: 
    82137            kmlDocument.elements.append( 
    83138                childWmsLayer.toKML(wmsRequestConfigElement, viewTypes, dir, dirUrl) 
    84139                ) 
     140 
     141        # Save the document into the KMZ file (this performs ZIP compression automatically). 
    85142        kmlDocument.save(filename) 
    86143        print 'Saved file "%s".' % filename 
    87144     
     145        # Return a network link that links to the KMZ file just created. 
    88146        return KMLNetworkLink(self.title, fileUrl, description = self.abstract, visible = False) 
    89147 
    90148class BottomWMSLayer(WMSLayer): 
    91149 
    92     '''[DOC]''' 
     150    ''' 
     151    Represents a bottom-level WMS layer (i.e. with no embedded sub-layers and a I{<wms:Dimension>} element. 
     152    @ivar name: Name of the layer 
     153    @ivar title: Title of the layer (more human readable than name) 
     154    @ivar abstract: Abstract of the layer (explanation of underlying data) 
     155    @ivar bbox: C{BBox} 
     156    @ivar timesteps: A list of C{pylab.dates.datetime.datetime} objects (the time dimension of the layer) 
     157    ''' 
    93158     
    94159    def __init__(self, name, title, abstract, bbox, timesteps): 
     
    135200    def toKML(self, wmsRequestConfigElement, viewTypes, parentDir, parentDirUrl): 
    136201        ''' 
    137         @param viewTyps: A list of View classes (but not instances), which define what kinds of view we are going  
    138                          to use to look at the data. 
    139                          ... 
    140         @return:         A KML.KMLFolder object representing a <kml:Folder> element with lots of <kml:GroundOverlay> 
    141                          elements, each standing for a different time segment. 
    142         ''' 
     202        Overrides the behaviour of C{WMSLayer.toKML}. Returns a C{KML.KMLFolder} object which represents 
     203        various view of the bottom layer, as per the C{viewTypes} parameter. 
     204        @param wmsRequestConfigElement: The <WMSRequest> element from the config file (containing information 
     205        about how WMS requests are to be made, e.g. which server to use, what resolution to use, etc.) 
     206        @type wmsRequestConfigElement: C{cElementTree.Element} 
     207        @param viewTypes: Determine in what ways the visible layer data is to be viewed. 
     208        @type viewTypes: A list of C{View} classes (note: classes, not instances!) 
     209        @param parentDir: (ignored) 
     210        layer will be contained directly in this directory. 
     211        @type parentDir: C{str} 
     212        @param parentDirUrl: (ignored) 
     213        @type parentDirUrl: C{str} 
     214        @return: A C{KML.KMLFolder} object containing individual views of the layers (as sub-folders). 
     215        ''' 
     216         
     217        # For each viewType, generate a new View object, that uses this layer (self) as a model and uses 
     218        # WMS request configuration wmsRequestConfigElement. The use that object to generate KML for this layer. 
    143219        kmlLayerFolder = KMLFolder(self.title, [], visible = False, opened = False) 
    144220        for viewType in viewTypes: 
     
    149225class View: 
    150226    ''' 
    151     Determines how BottomWMSLayer data can be viewed, i.e. how it can be converted into KML so it can be viewed 
    152     in Google Earth. In particular, it defines logical transforms of time-points into time-spans. 
     227    A view of a C{BottomWMSLayer} (as in "model-view-controller", an instance of this class is a view, 
     228    which the layer is the model). It determines how BottomWMSLayer data can be visualised in KML. 
     229    In particular, it defines logical transforms of time-points into time-spans. 
     230    @ivar layer: The layer being viewed. 
     231    @ivar wmsRequestConfigElement: A config element that defines format of WMS requests. 
    153232    ''' 
    154233 
     
    157236        Initialize the view. 
    158237        @param layer: Some views (not all) may need to "see" the layer data (although some ignore it). 
     238        @type layer: C{BottomWMSLayer} 
    159239        ''' 
    160240        self.layer = layer 
     
    179259 
    180260    def getCategory(self, timestep): 
     261        ''' 
     262        Abstract method, implemented in derived classes. Get a category in which the timestep belongs to. 
     263        @param timestep: A timestep. 
     264        @type timestep: C{pylab.dates.datetime.datetime} 
     265        @return: The category in which C{timestep} belongs to 
     266        ''' 
    181267        pass 
    182268 
    183269    def getCategoryDescription(self, category): 
    184         '''Abstract method, defined in derived classes. Get a human-readable description of the category.''' 
     270        ''' 
     271        Abstract method, defined in derived classes. Get a human-readable description of the category. 
     272        @param category: The category 
     273        @type categoty: Undefined (depends on category) 
     274        @return: A string describing the category (used for naming the category KML folder). 
     275        ''' 
    185276        pass 
    186277 
    187278    def _getSameDate(self, timestep): 
     279        ''' 
     280        A time-step transform. 
     281        @type timestep: C{pylab.dates.datetime.datetime} 
     282        ''' 
    188283        return timestep 
    189284 
    190285    def _getFirstDayOfMonth(self, timestep): 
     286        ''' 
     287        A time-step transform. 
     288        @type timestep: C{pylab.dates.datetime.datetime} 
     289        ''' 
    191290        return timestep.replace(day=1) 
    192291 
    193292    def _getMonthHence(self, timestep): 
     293        ''' 
     294        A time-step transform. 
     295        @type timestep: C{pylab.dates.datetime.datetime} 
     296        ''' 
    194297        if timestep.month+1 <= 12: 
    195298            return timestep.replace(month=timestep.month+1) 
     
    198301     
    199302    def _getYearHence(self, timestep): 
     303        ''' 
     304        A time-step transform. 
     305        @type timestep: C{pylab.dates.datetime.datetime} 
     306        ''' 
    200307        return timestep.replace(year=timestep.year+1) 
    201308 
    202309    def _getHalfPeriodEarlier(self, timestep): 
     310        ''' 
     311        A time-step transform. 
     312        @type timestep: C{pylab.dates.datetime.datetime} 
     313        @return: A timestep that is half of the viewed layer's period before C{timestep}. 
     314        ''' 
    203315        return timestep.replace(year = timestep.year-self.layer.getPeriod()/2) 
    204316 
    205317    def _getHalfPeriodLater(self, timestep): 
     318        ''' 
     319        A time-step transform. 
     320        @type timestep: C{pylab.dates.datetime.datetime} 
     321        @return: A timestep that is half of the viewed layer's period after C{timestep}. 
     322        ''' 
    206323        return timestep.replace(year = timestep.year+self.layer.getPeriod()/2) 
    207324 
    208325    def toKML(self): 
     326        ''' 
     327        ''' 
    209328 
    210329        def buildWMSRequest(timestep): 
Note: See TracChangeset for help on using the changeset viewer.