Changes between Initial Version and Version 1 of FDORfc57


Ignore:
Timestamp:
03/22/11 23:31:15 (14 years ago)
Author:
sunch
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FDORfc57

    v1 v1  
     1= FDO RFC 57 - Implement the GetFeatureInfo command for WMS provider  =
     2
     3This page contains a request for comments document (RFC) for the FDO Open Source project. 
     4More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.
     5
     6== Status ==
     7 
     8||RFC Template Version||(1.1)|| 
     9||Submission Date||March 23, 2011||
     10||Last Modified||Cheney Sun, March 23, 2011||
     11||Author||Cheney Sun||
     12||RFC Status||proposed||
     13||Implementation Status||under development||
     14||Proposed Milestone||3.7.0.0 ||
     15||Assigned PSC guide(s)||Orest Halustchak, Greg Boone||
     16||'''Voting History'''||(vote date)||
     17||+1||||
     18||+0||||
     19||-0||||
     20||-1||||
     21 
     22== Overview ==
     23
     24The RFC is to implement the GetFeatureInfo command for WMS provider.
     25
     26== Motivation ==
     27
     28GetFeatureInfo is an optional operation of WMS server. It is only supported for those Layers for which the attribute queryable="1" (true) has been defined or inherited.
     29The GetFeatureInfo operation is designed to provide clients of a WMS with more information about features in the pictures of maps that were returned by Get Map requests. The canonical use case for GetFeatureInfo is that a user sees the response of a Map request and chooses a point on that map for which to obtain more information.
     30Here is the table of the parameters of a GetFeatureInfo Request based on the 1.3.0 version:
     31||'''Request parameter'''       ||'''Mandatory/optional'''      ||'''Description'''||
     32||VERSION=1.3.0         ||M     ||Request version||
     33||REQUEST=GetFeatureInfo        ||M     ||Request name||
     34||map request part||    M       ||Partial copy of the Map request parameters that generated the map for which information is desired.||
     35||QUERY_LAYERS=layer_list ||    M       ||Comma-separated list of one or more layers to be queried||
     36||INFO_FORMAT=output_format     ||M     ||Return format of feature information (MIME type).||
     37||FEATURE_COUNT=number  ||O     ||Number of features about which to return information (default=1).||
     38||I=pixel_column        ||M     ||i coordinate in pixels of feature in Map CS||
     39||J=pixel_row   ||M     ||j coordinate in pixels of feature in Map CS||
     40||EXCEPTIONS=exception_format   ||O     ||The format in which exceptions are to be reported by the WMS (default= XML)||
     41Basically, the goal is that users must be able to not only connect to WMS services and add features to maps from those services; they should also be able to click on map features to get more information.[[BR]]
     42As to the 1.1.0 version, the standard employs the x = pixel_column and y = pixel_row to replace I = pixel_column and J = pixel_row.[[BR]]
     43More details regarding the WMS GetFeatureInfo request can be found in the WMS standards http://www.opengeospatial.org/standards/wms.
     44
     45== Proposed Solution ==
     46
     47The shortest WMS GetFeatureInfo implementation path would involve implementing GetFeatureInfo request within the current FDO WMS provider. The design solution would provide a custom command to users to retrieve the feature information: FdoWmsCommandType_GetFeatureInfo.[[BR]]
     48
     49'''•    Input of the GetFeatureInfo request'''[[BR]]
     50From the required parameters table above, we can see GetFeatureInfo requires almost all the parameters required by GetMap request and plus more, the custom command would also require the same input for Select command and extra parameters (i, j coordinate in pixels of feature in Map CS). [[BR]]
     51
     52'''•    Output of the GetFeatureInfo request'''[[BR]]
     53The format of responded message from the GetFeatureInfo request is defined by the WMS server. For example:[[BR]]
     54  <Format>text/plain</Format> [[BR]]
     55  <Format>text/html</Format>[[BR]]
     56Currently, the WMS implementation specification doesn’t define a standard format for it. So, the solution is to return a FdoString* type pointer by this command. If user set the FEATURE_COUNT greater than 1, the information for multiple candidate features will be returned. However, we don’t parse the returned information since no standard regarding the format and client should take the responsibility to parse it.  For example the following text is returned from one server to response the GetFeatureInfo request.[[BR]]
     57Layer 'IBA'[[BR]]
     58     Feature 6:[[BR]]
     59     SITEID = 'NU009'[[BR]]
     60     NAME = 'Queen Maud Lowlands' [[BR]]
     61     LINK = 'http://www.bsc-eoc.org/iba/site.jsp?siteID=NU009' [[BR]]
     62
     63
     64     Feature 66:[[BR]]
     65     SITEID = 'NU089'[[BR]]
     66     NAME = 'Middle Back River'[[BR]]
     67     LINK = 'http://www.bsc-eoc.org/iba/site.jsp?siteID=NU089' [[BR]]
     68
     69However, the following XML formatted message will return if issue the command to a MapGuide server. [[BR]]
     70<?xml version=”1.0”, encoding=”UTF-18”?> [[BR]]
     71   < FeatureInfoCollection>[[BR]]
     72     < FeatureInfo layer = “Sample/Layers/Districts”> [[BR]]
     73       <Property name=”name” value = “Voting District Three”/> [[BR]]
     74       <Property name =”Url” value=””/> [[BR]]
     75       <Property name=Key value=3/> [[BR]]
     76       <Property name=”Autogenerated_SDF_ID” value=6/> [[BR]]
     77     </FeatureInfo> [[BR]]
     78   </FeatureInfoCollection> [[BR]]
     79Note: we can parse the response value and return a class if WMS spec defines a standard format in the future.
     80
     81'''•    GetFeatureInfo custom command interface'''[[BR]]
     82
     83{{{
     84/// \brief
     85/// The FdoWmsIGetFeatureInfo interface defines the
     86/// FdoWmsIGetFeatureInfo command, which retrieves more information
     87/// about features in the maps. The Execute operation
     88/// returns a FdoString* type pointer pointing to the feature information.
     89class FdoWmsIGetFeatureInfo : public FdoICommand
     90{
     91    friend class FdoIConnection;
     92public:
     93    /// \brief
     94    /// Execute the FdoWmsIGetFeatureInfo command and returns a
     95    /// FdoString* pointer, which points to the feature information returned
     96          /// by the WMS server.
     97    ///
     98    /// \return
     99    /// Returns string contains feature information from the WMS server
     100    ///
     101    FDO_API virtual FdoString * Execute() = 0;
     102
     103    /// \brief
     104    /// Set the feature class name for which feature information
     105    /// will be retrieved. This function is mandatory; if not specified or the feature class
     106    /// name can’t be found in the schema, execution of the command will throw an
     107    /// exception.
     108    ///
     109    /// \param value
     110    /// Input the feature class name.
     111    ///
     112    /// \return
     113    /// Returns nothing
     114    ///
     115    FDO_API virtual void SetFeatureClassName(FdoIdentifier* values) = 0;
     116
     117    /// \brief
     118    /// Get the name of the feature class for which feature information
     119    /// will be retrieved.
     120    ///
     121    /// \return
     122    /// Input the query feature class name.
     123    ///
     124    FDO_API virtural FdoIdentifier * GetFeatureClassName() = 0;
     125
     126    /// \brief
     127    /// Set the position (X, Y) which indicates a point of interest on the map that was
     128    /// produced by the embedded GetMap request.The point (X, Y) is a
     129    /// point in the (i, j) space defined by the Map CS.
     130    /// This function is mandatory; if not specified,
     131    /// execution of the command will throw an exception.
     132    ///
     133    /// \param pos
     134    /// Input the point's coordinate value (X, Y)
     135    ///
     136    /// \return
     137    /// Return nothing
     138    ///
     139   FDO_API virtual void SetPosition(FdoIDirectPosition* pos) = 0;
     140
     141    /// \brief
     142    /// Get the position (X, Y) which indicates a point of interest on the map that was
     143    /// produced by the embedded GetMap request. The point (X, Y) is a
     144    /// point in the (i, j) space defined by the Map CS.
     145    ///
     146    /// \return
     147    /// Return the interesting position.
     148    ///
     149    FDO_API virtual FdoIDirectPosition GetPosition() = 0;
     150
     151    /// \brief
     152    /// Set the number of features about which to return information (default=1).
     153    ///
     154    /// \param featureCount
     155    /// The number of the features to query.
     156    ///
     157    /// \return
     158    /// Returns nothing
     159    ///
     160    FDO_API virtual void SetFeatureCount(FdoInt32 featureCount = 1) = 0;
     161
     162    /// \brief
     163    /// Get the number of features about which to return information.
     164    ///
     165    /// \return
     166    /// Returns candidate feature number.
     167    ///
     168    FDO_API virtual FdoInt32 GetFeatureCount () = 0;
     169};
     170}}}
     171In this class, both methods GetFeatureClassNames and SetFeatureClassNames are used to get/set the feature class collection which would be mapped to WMS layers in order to query the relevant feature information. [[BR]]
     172
     173'''•    Example''' [[BR]]
     174The GetFeatureInfo custom command will be used like below:
     175
     176{{{
     177 FdoPtr<FdoWmsIGetFeatureInfo> cmdGFI = static_cast<FdoWmsIGetFeatureInfo*> (connection->CreateCommand(FdoWmsCommandType_GetFeatureInfo));
     178FdoPtr<FdoIdentifier> id = FdoIdentifier::Create(L”Park”);
     179cmdGFI->SetFeatureClassNames(id);
     180FdoPtr<FdoFgfGeometryFactory> gf = FdoFgfGeometryFactory::GetInstance();
     181FdoPtr<FdoIDirectPosition> pt = gf->CreatePositionXY(-1000, 1000);
     182cmdGFI->SetPosition(pt);
     183FdoStringP featureInfo = cmdGFI->Execute ();
     184}}}
     185Since lot of same parameters required with GetMap request, the execute function of this custom command will be similar with the select command. The difference is to pass the extra i, j values and fire the GetFeatureInfo request to WMS server. What’s more, share the same codes between select command and GetFeatureInfo custom command should be considered seriously.[[BR]]
     186
     187Similar to the GetMap command, the parameters regarding the GetMap parts should be obtained from the override configuration. If it’s not customized, the default parameters will be gotten from capabilities documents (returned from GetCapabilities).  One note is that the command should generally be called after the GetMap request; otherwise, the returned result is probably unexpected if the parameters are wrongly specified.
     188
     189== Implications ==
     190
     191•       A new command FdoWmsCommandType_GetFeatureInfo is added for WMS provider.
     192
     193== Test Plan ==
     194
     195Add unit tests into WMS provider to test the new command.
     196
     197== !Funding/Resources ==
     198
     199Autodesk to provide resources / funding