wiki:csmlapi

Version 6 (modified by domlowe, 13 years ago) (diff)

Added proposed csml API for review

CSML API (for CSML Version 2)

While 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.

The 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().

Below is the proposed API in pseudo python for CSML version 2. I've only shown the bits of the api that are intended to be exposed rather than all the 'private' methods:

Comments welcome.

Dataset

class Dataset:
    #a csml dataset
    #note the name dataset might change in csml v2
    def parse(self,csmlfile:
        #must be provided with a csml file.
        #the contents of the csmlfile becomes the Dataset

    def getSecurity(self):
        #get the security conditions for the csml document 
       returns: list of dgSecurityConditions (in effect, authority,role format
        
    def getFeatureList(self):
        returns: list of named features (by id) in that document     
        #do we want to know the type too?

    def getFeature(self, featureID):
        #from the id list returned by getFeatureList, select a feature
        returns: a feature object (eg GridSeriesFeature, PointFeature etc).

Common to all features

    #these methods can be called on all types of features.
    def getAffordances(self)         
        returns: list of allowed operations (eg ['subsetToPointSeries', 'subsetToPoint']
        
    def getDomain(self):       
        returns: dictionary of axis names (gml:id) and values

    def getDomainCRS(self):
        returns: a CRSystem object

Coordinate Reference System

class CRSystem:
     #Has attributes:
     srsName  e.g. ndg:crs:xyht
     srsDimension e.g. 4
     axisLabels e.g. Lon Lat Height Time
    
    def identifyDomainAxis(self, label):
        #eg. crs.identifyDomainAxis('Height')
        # might return 'h'
         #so the domain might be {T:1,2,3, lon:0,20,40, lat:60,70, h:100, 200, 300}
        #while the crs is 'Lon Lat Height Time'        
        #internally csml knows which axis of the domain corresponds to the axes of the CRS, and identifyDomainAxis is a way to expose this.
        returns: axis name corresponding to label

Container

class CSMLContainer:
        #the container assists in performing multiple subset operations on different features yet delivering the result in a single csml file.

    def add(self, featureplusfile):
        #add the result of a subsetting operation to the container
       
        
    def getContents(self):
        returns: list of paths to csml file and netcdf files   

GridSeriesFeature

class GridSeriesFeature:
    def subsetToGridSeries(self, csmlpath=None, ncpath=None,**kwargs)
    #csmlpath=path of output csml file
    #ncpath = path of output netcdf file
    #**kwargs = subset request
        return pathToNetcdfFile, pathTocsmlFile
    
     def subsetToPointSeries(self, csmlpath=None, ncpath=None,**kwargs)
    #csmlpath=path of output csml file
    #ncpath = path of output netcdf file
    #**kwargs = subset request
        return pathToNetcdfFile, pathTocsmlFile

    #other subsets.... tba

PointSeriesFeature

class PointSeriesFeature:
    def subsetToPoint(self, csmlpath=None, ncpath=None,**kwargs)
    return pathToNetcdfFile, pathTocsmlFil

#okay, I'm not going to go through all the feature subsetting combinations now! They all work the same way basically. 

#Do we want to have an option to just return data e.g.
    def subsetToPoint(self, csmlpath=None, ncpath=None, dataOnly=None,**kwargs)
        returns: ? NumericArray only?