Changes between Version 5 and Version 6 of csmlapi


Ignore:
Timestamp:
11/01/07 16:13:26 (13 years ago)
Author:
domlowe
Comment:

Added proposed csml API for review

Legend:

Unmodified
Added
Removed
Modified
  • csmlapi

    v5 v6  
    1  = CSML API = 
     1 = CSML API (for CSML Version 2) = 
    22 
    33While the CSML parser provides a collection of objects it is not ideal to interact with these low level objects as it requires detailed knowledge of CSML structure. 
     
    55The CSML API therefore exists as a collection of higher level methods that typically provide a wrapper to the lower level parser objects e.g. getListOfFeatures(). The API also provides a place to attach 'operations' to features e.g.subsetThisFeature().  
    66 
    7 Below is a list classes and methods/operations (in practice they are the same thing if not conceptually!) some of which are implemented others which are  required.  
     7Below is the proposed API in pseudo python for CSML version 2. 
     8I've only shown the bits of the api that are intended to be exposed rather than all the 'private' methods: 
    89 
    9 (note this is likely to develop with CSML V2) 
     10Comments welcome. 
     11== Dataset == 
     12{{{ 
     13#!python 
     14class Dataset: 
     15    #a csml dataset 
     16    #note the name dataset might change in csml v2 
     17    def parse(self,csmlfile: 
     18        #must be provided with a csml file. 
     19        #the contents of the csmlfile becomes the Dataset 
    1020 
    11  == Dataset() ==  
    12 This is the 'root level' class, and the gateway to a CSML document. 
     21    def getSecurity(self): 
     22        #get the security conditions for the csml document  
     23       returns: list of dgSecurityConditions (in effect, authority,role format 
     24         
     25    def getFeatureList(self): 
     26        returns: list of named features (by id) in that document      
     27        #do we want to know the type too? 
    1328 
    14  === ''methods:'' === 
     29    def getFeature(self, featureID): 
     30        #from the id list returned by getFeatureList, select a feature 
     31        returns: a feature object (eg GridSeriesFeature, PointFeature etc). 
     32}}} 
     33== Common to all features == 
     34{{{ 
     35#!python 
     36    #these methods can be called on all types of features. 
     37    def getAffordances(self)          
     38        returns: list of allowed operations (eg ['subsetToPointSeries', 'subsetToPoint'] 
     39         
     40    def getDomain(self):        
     41        returns: dictionary of axis names (gml:id) and values 
    1542 
    16 ''parse(self,csmlfile):'' 
    17 #this parses a csml file into a (previously empty) dataset object 
     43    def getDomainCRS(self): 
     44        returns: a CRSystem object 
     45}}} 
    1846 
    19 ''getFeatureList(self):'' 
    20 #returns a list of feature ids for the features contained in the dataset 
     47== Coordinate Reference System == 
    2148 
    22 ''getFeature(self, featureID):'' 
    23 #returns a single feature object (eg a !PointSeriesFeature) 
     49{{{ 
     50#!python 
     51class CRSystem: 
     52     #Has attributes: 
     53     srsName  e.g. ndg:crs:xyht 
     54     srsDimension e.g. 4 
     55     axisLabels e.g. Lon Lat Height Time 
     56     
     57    def identifyDomainAxis(self, label): 
     58        #eg. crs.identifyDomainAxis('Height') 
     59        # might return 'h' 
     60         #so the domain might be {T:1,2,3, lon:0,20,40, lat:60,70, h:100, 200, 300} 
     61        #while the crs is 'Lon Lat Height Time'         
     62        #internally csml knows which axis of the domain corresponds to the axes of the CRS, and identifyDomainAxis is a way to expose this. 
     63        returns: axis name corresponding to label 
    2464 
    25 ''getFileExtract(self,extractID):'' 
    26 #returns a single file extract object (eg a !NetCDFExtract)  
     65}}} 
    2766 
    28 ''getSecurity(self):'' 
    29 #returns a dictonary containing attributeAuthority(ies) and role(s) 
     67 == Container == 
     68{{{ 
     69#!python 
     70class CSMLContainer: 
     71        #the container assists in performing multiple subset operations on different features yet delivering the result in a single csml file. 
    3072 
    31  == AbstractFeature() == 
    32 #this is the base class for all features 
    33  === ''methods:'' === 
    34 ''getAllowedSubsettings(self):'' 
    35 #returns a list of subsetting operations avalable: ['none'] for AbstractFeature 
     73    def add(self, featureplusfile): 
     74        #add the result of a subsetting operation to the container 
     75        
     76         
     77    def getContents(self): 
     78        returns: list of paths to csml file and netcdf files    
     79}}} 
    3680 
    37  == AbstractFileExtract() == 
    38 #this is the base class for all file extract classes 
     81== !GridSeriesFeature ==  
    3982 
    40  === ''methods:'' === 
    41 ''getData(self,  fileposition=None, times=None, **kwargs):'' 
    42 #Given a file extract, get the data for that extract.  
     83{{{ 
     84#!python 
     85class GridSeriesFeature: 
     86    def subsetToGridSeries(self, csmlpath=None, ncpath=None,**kwargs) 
     87    #csmlpath=path of output csml file 
     88    #ncpath = path of output netcdf file 
     89    #**kwargs = subset request 
     90        return pathToNetcdfFile, pathTocsmlFile 
     91     
     92     def subsetToPointSeries(self, csmlpath=None, ncpath=None,**kwargs) 
     93    #csmlpath=path of output csml file 
     94    #ncpath = path of output netcdf file 
     95    #**kwargs = subset request 
     96        return pathToNetcdfFile, pathTocsmlFile 
    4397 
    44 Note fileposition is for when a file extract describes multiple files. Kwargs contains a dimensional subsetting request e.g. (X=blah, Y=blah, Z=blah) 
     98    #other subsets.... tba 
     99}}} 
    45100 
    46  == GridSeriesFeature(!AbstractFeature) ==  
    47  === ''methods:'' === 
    48 ''getAllowedSubsettings(self):'' 
    49 #returns a list of subsetting operations avalable: ['subsetToGridSeries','subsetTo...'?]   
     101== !PointSeriesFeature == 
     102{{{ 
     103#!python 
     104class PointSeriesFeature: 
     105    def subsetToPoint(self, csmlpath=None, ncpath=None,**kwargs) 
     106    return pathToNetcdfFile, pathTocsmlFil 
    50107 
    51 ''getDomainReference(self):'' 
    52 #Returns a dictionary containing times that make up the domain reference. Of the form: ['t':times] 
     108#okay, I'm not going to go through all the feature subsetting combinations now! They all work the same way basically.  
    53109 
    54 ''getDomainComplement(self):'' 
    55 #Returns a dictionary containing axis values. Of the form [AxisName:Values] 
     110#Do we want to have an option to just return data e.g. 
     111    def subsetToPoint(self, csmlpath=None, ncpath=None, dataOnly=None,**kwargs) 
     112        returns: ? NumericArray only? 
     113}}} 
    56114 
    57 ''getDomain(self):'' 
    58 #Returns a dictionary containing both the domain refernce and the domain complement. 
    59  
    60 ''subsetToGridSeries(self,, timeSubset,  csmlpath=None, ncpath=None,**kwargs):'' 
    61 #kwargs contains subset requets 
    62 #Returns a path to a subsetted CSML file, a subsetted NetCDF file and also the size of the data returned. 
    63  
    64  
    65 To be continued...