source: DPPP/kml/csml2kml/docs/wiki.txt @ 3322

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/DPPP/kml/csml2kml/docs/wiki.txt@3322
Revision 3322, 7.5 KB checked in by mkochan, 12 years ago (diff)
Line 
1Project Wiki
2SVN repository currently contains 2 directories which are supposed to serve as root directories of future Python eggs, usable for easy re-distribution across BADC machines.
3These are:
4.     Located at <code>kml/csml2kml/python/csml2kml</code> - contains convertors from CSML to KML (although CSML is required to be accompanied by context/configuration files or additional GML documents providing context for the conversion)
5.     Located at <code>kml/csml2kml/python/pylonsstack</code> - contains code for generating dynamic web content, implemented using the Pylons web framework. This has to be used whenever some code has to be run at view time (from user.s perspective). This is because Google Earth does not allow running of any code on the client side and therefore this must be provided via dynamic web content, served on BADC side
6In addition to these, there are two directories:
7.  <code>kml/csml2kml/testdata</code> contains all testing data (inputs) . these will later be split into the appropriate eggs, so that tests can be run from eggs
8.  <code>kml/csml2kml/outputs</code> contains all outputs from tests
9
10===KMLDocument===
11
12Encapsulation of a KML document is achieved via the module <code>KMLDocument.py</code>. The whole KML document
13can be contained in an <code>KMLDocument.KMLDocument</code> object; this object in turn contains objects derived
14from class <code>KMLDocument.KMLElement</code>. Once a <code>KMLDocument</code> object has been generated,
15it can be saved into a file using the method <code>KMLDocument.save()</code> -- actual KML is generated only
16during saving.
17
18===Convertors===
19
20Currently only CSML documents containing solely csml:GridSeriesFeature and csml:PointSeriesFeature elements are supported.
21
22===GridSeriesConvertor===
23
24Example run is contained in <code>kml/csml2kml/python/csml2kml/tests/testGridSeriesConvertor.py</code>.
25This test reads in the climate modelling file <code>clim_10.csml</code> with month/decade values for various
26csml:GridSeriesFeature's. The CSML file does not contain the grid data themselves -- these are read in from WMS.
27Since this information is not part of the CSML file, there must be a config file supplied as well,
28which contains the context for the conversion. Its format is as follows:
29<pre><nowiki>
30<CSML2KMLConfig>
31  <CSMLGridSeriesFeatureWMSRequest>
32    <URL>http://www-devel.ipcc-data.org/maps/wms/obs</URL>
33    <ServiceVersion>1.1.1</ServiceVersion>
34    <ImageFormat>image/png</ImageFormat>
35    <ImageWidth>960</ImageWidth>
36    <ImageHeight>480</ImageHeight>
37    <CRS>EPSG:4326</CRS>
38    <LayerName>#FILENAME_EXCL_SUFFIX#/#FEATURE_NAME#</LayerName>
39    <LongitudeBounds>UNCONSTRAINED</LongitudeBounds>
40    <LatitudeBounds>UNCONSTRAINED</LatitudeBounds>
41  </CSMLGridSeriesFeatureWMSRequest>
42  <View name="Whole century">
43    <SplitTimeStepsBy></SplitTimeStepsBy>
44    <LogicalDateTimeTransform>20_CENTURY_DECADE</LogicalDateTimeTransform>
45    <LogicalDateTimeDelta>MONTH_HENCE</LogicalDateTimeDelta>
46  </View>
47  <View name="Compare decades">
48    <SplitTimeStepsBy>year</SplitTimeStepsBy>
49    <CategoryNamingPattern>Decade of #VERBATIM#</CategoryNamingPattern>
50    <LogicalDateTimeTransform>FIRST_DAY_OF_MONTH</LogicalDateTimeTransform>
51    <LogicalDateTimeDelta>MONTH_HENCE</LogicalDateTimeDelta>
52  </View>
53  <View name="Compare months">
54    <SplitTimeStepsBy>month</SplitTimeStepsBy>
55    <CategoryNamingPattern>#MONTH#</CategoryNamingPattern>
56    <LogicalDateTimeTransform>FIRST_DAY_OF_MONTH</LogicalDateTimeTransform>
57    <LogicalDateTimeDelta>DECADE_HENCE</LogicalDateTimeDelta>
58  </View>
59</CSML2KMLConfig>
60</nowiki></pre>
61The <code>CSMLGridSeriesFeatureWMSRequest</code> element contains information about the WMS to be used
62from retrieval. Each <code>View</code> element describes a different way of viewing the data,
63i.e. how they should be organized in Google Earth's left panel. This also determines how they can be animated.
64
65The code for csml:GridSeriesFeature's conversion is organised in the following modules:
66. GridSeriesConvertor.py -- contains class <GridSeriesConvertor> which performs the conversion
67. csmlwrappers.py -- contains wrapper classes which wrap around various CSML Features.
68  Currently there is only class <code>GridSeriesFeatureWrapper</code>.
69. kmlfeatures.py -- encapsulation of CSML features as KML elements. Does not use <code>KMLDocument</code>
70  and is only used by <code>GridSeriesConvertor</code>.
71
72===PointSeriesConvertor===
73
74Note: A different design approach has been taken for development of code for conversion of documents containing
75csml:PointSeriesFeature's. A module named <code>PointSeriesConvertor.py</code> does exist, however,
76<code>csmlwrappers.py</code> and <kmlfeatures.py> are <i>not</i> used by it.
77
78Example run is contained in kml/csml2kml/python/csml2kml/tests/testPointSeriesConvertor.py.
79This test reads in a GML document from an arbitrary URL (which normally is a GeoServer call).
80It also requires a configuration object, which sets context for the conversion.
81The format of input is <i>not</i> CSML, but rather XML derived from GML that specifies locations
82of meteorological stations; each station can have several csml:PointSeriesFeature's associated with it.
83Since it was desirable to have plots of features available,
84the KML that is generated by PointSeriesConvertor merely coantains references to a web service
85on BADC side that draws the plots.
86
87
88<pre><nowiki>
89...
90</nowiki></pre>
91
92Note: The same server should return CSML of individual CSML features for any station.
93At the moment, how exactly this will be done is a matter of debate.
94
95The configuration is obtained from a config file which has format similar to this:
96<pre><nowiki>
97<CSML2KMLConfig>
98  <CSMLStationPointSeries>
99    <name>MIDAS stations (example)</name>
100    <UseRegions>yes</UseRegions>
101    <GeoServerRequest>
102      <URL>http://bond.badc.rl.ac.uk:8089/dummyGeoServer/GetStationCSMLFeatures?gml_id=MIDAS_Stations</URL>
103      <BalloonTemplate>&lt;img src="http://bond.badc.rl.ac.uk:8089/csmlGrapher/plot?feature_id=$[feature_id]"&gt;</BalloonTemplate>
104      <StationData>
105        <Datum name="feature_id">#ID#</Datum>
106      </StationData>
107    </GeoServerRequest>
108  </CSMLStationPointSeries>
109</CSML2KMLConfig>
110</nowiki></pre>
111The element <code>GeoServerRequest</code> determines how stations list should be obtained (from which URL)
112and how information on each station should be shown in a balloon that pops out in Google Earth when a station
113is clicked. Each station can how certain data associated with it, which are substituted into the template.
114Using the <code>#ID#</code> value will in turn be substituted by the individual feature's ID.
115
116When the config-file tag <code>UseRegions</code> is set to "yes", the convertor is capable of generating KML
117with a very large number of stations, possibly tens of thousands. This would normally cause slow rendering in Google Earth if all stations were visible at the same time, but it is possible to use sectioning  hierarchically into ever smaller regions (using the kml:Region tag), so that the actual stations are loaded and visible only for closer zooms. In code, this is solved using splitting each geographical region (a rectangle) into 4 smaller regions, and continuing until a small number of stations (10) is present in that region. In KML, the stations are saved as kml:Placemark elements in a hierarchy of kml:Folder elements.
118
119===The web server side===
120
121As mentioned, all functionality which must be executed at run time must be delegated to a BADC web service.
122For kml:GridSeriesFeature datasets, the grid data is read from a WMS server.
123
124For kml:PointSeriesFeature datasets, there is a need to plot/graph the data
Note: See TracBrowser for help on using the repository browser.