Changeset 3598 for DPPP


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

Extended documentation of Station and StationConvertor?.

Location:
DPPP/kml/csml2kml
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • DPPP/kml/csml2kml/docs

    • Property svn:ignore
      •  

        old new  
        1 *.pyc 
         1* 
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/Station.py

    r3558 r3598  
    1 ''' 
    2 Contains class NPStation, which represents the <np:Station> element 
    3 (the schema for namespace "np" is located at: http://130.246.76.98:8084/geoserver/schemas/wfs/1.1.0/wfs.xsd). 
    4 Also, for convenience, contains class WFSStationCollection, which represents a <wfs:FeatureCollection> 
    5 that contain *specifically* <np:Station> elements! 
    6 ''' 
    7  
    81from cElementTree import XML 
    92 
    10 npXmlNamespace = 'http://ndg.nerc.ac.uk/np' 
     3npXmlNamespace = 'http://ndg.nerc.ac.uk/np'  # the namespace in which the Station element is defined 
    114 
    125class NPStation: 
    13     '''Represents a ground meteorological station, identified by id, with description (desc), located at (lon,lat)''' 
     6    ''' 
     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}. 
     9    ''' 
    1410 
    1511    def __init__(self, id = None, desc = None, lon = None, lat = None, csmlFeatureIds = None): 
    1612        ''' 
    17         The initialiser. It is possible (and typical) not to initialise using it but rather leave 
    18         values undefined and parse them in from GML. 
     13        The initialiser. It is recommended not to pass any optional value (i.e. use only C{NPStation()}) 
     14        and later call C{parseString} or C{parseXML}. 
     15        @param id: Station identifier (e.g. "midas.station.1") 
     16        @type id: str 
     17        @param desc: Station description (e.g. "FAIR ISLE") 
     18        @type desc: str 
     19        @type lon: float 
     20        @type lat: float 
     21        @type csmlFeatureIds: str list 
    1922        ''' 
    2023        self.id = id 
     
    2427 
    2528    def parseString(self, str): 
     29        ''' 
     30        Parse in the station from a string C{str} containing XML.  
     31        ''' 
    2632        stationElement = XML(str) 
    2733        self.parseXML(stationElement) 
    2834 
    2935    def parseXML(self, stationElement): 
     36        ''' 
     37        Parse in the station directly from an C{cElementTree.Element} object. 
     38        @param stationElement: An element containing station in XML form. 
     39        @type stationElement: C{cElementTree.Element} 
     40        ''' 
     41 
     42        # Extract the identifier, short description, and longitude and latitute 
    3043        (stationNameElement, stationIDElement, locationElement, featuresElement) = stationElement.getchildren() 
    3144        pointElement = locationElement.getchildren()[0] 
     
    3447        self.id = stationElement.get('{http://www.opengis.net/gml}id') 
    3548        self.desc = stationNameElement.text 
     49 
     50        # Extract the IDs of the associated CSML features 
    3651        self.csmlFeatureIds = [] 
    3752        for stationsFeatureElement in featuresElement.getchildren(): 
     
    4762 
    4863class WFSStationCollection: 
     64    ''' 
     65    Represents a <wfs:FeatureCollection> element that contains *specifically* <np:Station> elements! 
     66    @ivar stations: A list of C{NPStation}'s contained in the collection. 
     67    ''' 
    4968 
    5069    def __init__(self): 
     
    5372    def parseString(self, str): 
    5473        ''' 
    55         Parse in the <wfs:FeatureCollection> element returned from GeoServer, save individual stations. 
    56         Use if your WFS subset of GML is stored in a string. 
     74        Parse in the <wfs:FeatureCollection> element returned from GeoServer, and save individual stations. 
     75        @param str: A string containing the the <wfs:FeatureCollection> element. 
     76 
    5777        ''' 
    5878        featureCollectionElement = XML(str) 
     
    6282        ''' 
    6383        Parse in the <wfs:FeatureCollection> element returned from GeoServer, save individual stations. 
    64         Use if your WFS subset of XML is stored in an ElementTree.Element object. 
     84        Use if your WFS subset of XML is stored in an C{cElementTree.Element} object. 
    6585        ''' 
    6686        featureMembersElement = featureCollectionElement.getchildren()[0] 
  • DPPP/kml/csml2kml/python/csml2kml/csml2kml/StationConvertor.py

    r3582 r3598  
    1212class StationConvertor: 
    1313    ''' 
    14     Converter from GML+CSML to KML. 
    15     Contains functionality for converting GML containing a collection of Station elements into KML. 
     14    Contains functionality for converting a collection of <np:Station>'s into a KML or a KMZ file. 
    1615    ''' 
    1716     
    1817    def __init__(self, config): 
    19         '''Initialize the convertor and set it up according to the config file.''' 
     18        ''' 
     19        Initialize the convertor and set it up according to the configuration. 
     20        @param config: An element containing contents of a <NPStations2KML> element from a XML config file. 
     21        @type config: C{cElementTree.Element} 
     22        ''' 
    2023         
    2124        self.config = config 
     
    4952 
    5053    def _npStationToKmlPlacemark(self, npStation): 
    51         '''Converts a Station.NPStation object into it's KML.KMLPlacemark representation''' 
     54        '''Converts a C{Station.NPStation} object into it's C{KML.KMLPlacemark} representation''' 
    5255        return KMLPlacemark(npStation.id, npStation.desc, npStation.lon, npStation.lat, 
    5356                            styleID = self.placemarkKmlStyle.id, data = self.stationData 
     
    5659    def _buildKmlDocumentDirectly(self, kmlDocument, npStations): 
    5760        ''' 
    58         Returns an object of the KMLDocument class, kmlDocument, which will contain each station 
    59         represented by a placemark directly contained in the document (i.e. no intermediate folders). 
     61        Returns a C{KMLDocument} object with stations represented by KML placemarks directly contained 
     62        in the document (i.e. without any intermediate folders). 
     63        @param kmlDocument: A document to which the folder hierarchy should be attached. 
     64        @type kmlDocument: C{KML.KMLDocument} 
     65        @param npStations: A list of stations to be contained in the hierarchy. 
     66        @type npStations: List of C{Station.NPStation} objects. 
     67        @return: A C{KML.KMLDocument} object. 
    6068        ''' 
    6169        for npStation in npStations: 
     
    6573    def _buildKmlDocumentUsingSections(self, kmlDocument, npStations): 
    6674        ''' 
    67         Returns an object of the KMLDocument class, kmlDocument, which contains the stations 
    68         organized into a hierarchy of folders, each containing ever smaller section of land.  
    69         The root of this hierarchy, a KMLFolder object, gets attached to the document, 
    70         and is "closed" i.e. it is not possible to open it in Google Earth's list view. 
     75        Returns a C{KMLDocument} object containing stations as KML placemarks wrapped in a hierarchy 
     76        of C{KMLFolder}'s with associated C{KMLRegion}'s. The regions are recursively decreasing in size. 
     77        @param kmlDocument: A document to which the folder hierarchy should be attached. 
     78        @type kmlDocument: C{KML.KMLDocument} 
     79        @param npStations: A list of stations to be contained in the hierarchy. 
     80        @type npStations: List of C{Station.NPStation} objects. 
     81        @return: A C{KML.KMLDocument} object. 
    7182        ''' 
    7283 
     
    115126    def convert(self): 
    116127        ''' 
    117         Convert GML input from GeoServer (containing the <Station> tags with station information) 
    118         to the KML representation. 
     128        Perform the conversion.  
     129        This will produce a KML or KMZ file, depending on the suffix of the output file as defined in the config file.  
     130 
     131        The stations will be organised depending on the C{UseRegions} setting in the config file: 
     132          - if C{UseRegions} is set to C{no}, 
     133            stations will be included simply as a list of KML placemarks. 
     134          - if C{UseRegions} is set to C{yes}, 
     135            stations will be divided into a hierarchy of KML regions, by recursively splitting 
     136            the the covered are into 4 smaller regions, starting with the whole globe.  
     137            The actual station KML placemarks will be placed at the bottom of the hierarchy. 
     138            Therefore, they will be visible only for closer zooms onto the ground. 
    119139        ''' 
    120140 
Note: See TracChangeset for help on using the changeset viewer.