Changes between Version 5 and Version 6 of csmlapi

11/01/07 16:13:26 (13 years ago)

Added proposed csml API for review


  • csmlapi

    v5 v6  
    1  = CSML API = 
     1 = CSML API (for CSML Version 2) = 
    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().  
    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: 
    9 (note this is likely to develop with CSML V2) 
     10Comments welcome. 
     11== Dataset == 
     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 
    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 
     25    def getFeatureList(self): 
     26        returns: list of named features (by id) in that document      
     27        #do we want to know the type too? 
    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). 
     33== Common to all features == 
     36    #these methods can be called on all types of features. 
     37    def getAffordances(self)          
     38        returns: list of allowed operations (eg ['subsetToPointSeries', 'subsetToPoint'] 
     40    def getDomain(self):        
     41        returns: dictionary of axis names (gml:id) and values 
    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 
    19 ''getFeatureList(self):'' 
    20 #returns a list of feature ids for the features contained in the dataset 
     47== Coordinate Reference System == 
    22 ''getFeature(self, featureID):'' 
    23 #returns a single feature object (eg a !PointSeriesFeature) 
     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 
     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 
    25 ''getFileExtract(self,extractID):'' 
    26 #returns a single file extract object (eg a !NetCDFExtract)  
    28 ''getSecurity(self):'' 
    29 #returns a dictonary containing attributeAuthority(ies) and role(s) 
     67 == Container == 
     70class CSMLContainer: 
     71        #the container assists in performing multiple subset operations on different features yet delivering the result in a single csml file. 
    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 
     77    def getContents(self): 
     78        returns: list of paths to csml file and netcdf files    
    37  == AbstractFileExtract() == 
    38 #this is the base class for all file extract classes 
     81== !GridSeriesFeature ==  
    40  === ''methods:'' === 
    41 ''getData(self,  fileposition=None, times=None, **kwargs):'' 
    42 #Given a file extract, get the data for that extract.  
     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 
     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 
    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 
    46  == GridSeriesFeature(!AbstractFeature) ==  
    47  === ''methods:'' === 
    48 ''getAllowedSubsettings(self):'' 
    49 #returns a list of subsetting operations avalable: ['subsetToGridSeries','subsetTo...'?]   
     101== !PointSeriesFeature == 
     104class PointSeriesFeature: 
     105    def subsetToPoint(self, csmlpath=None, ncpath=None,**kwargs) 
     106    return pathToNetcdfFile, pathTocsmlFil 
    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.  
    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? 
    57 ''getDomain(self):'' 
    58 #Returns a dictionary containing both the domain refernce and the domain complement. 
    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. 
    65 To be continued...