Changes between Version 8 and Version 9 of ZooWorkshop/FOSS4GJapan/CreatingOGRBasedWebServices

Timestamp:

Oct 15, 2010, 6:16:34 PM (14 years ago)

Author:

djay

Comment:

--

ZooWorkshop/FOSS4GJapan/CreatingOGRBasedWebServices

@@ -571 +571 @@
 
 == Creating Services for other functions (ConvexHull and Centroid) ==
+
+As the Boundary sample service code is available, you can now easily add ConvexHull and Centroid functions as they take exactly the same number of arguments : Only one geometry. The details for implementing and deploying the ConvexHull Service are provided bellow, and we will let you do the same thing for the Centroid one.
+
+=== C Version ===
+
+Please add first the following code to the service.c source code :
+
+{{{
+#!c
+int ConvexHull(maps*& conf,maps*& inputs,maps*& outputs){
+  OGRGeometryH geometry,res;
+  map* tmp=getMapFromMaps(inputs,"InputPolygon","value");
+  if(tmp==NULL)
+    return SERVICE_FAILED;
+  map* tmp1=getMapFromMaps(inputs,"InputPolygon","mimeType");
+  if(strncmp(tmp1->value,"application/json",16)==0)
+    geometry=OGR_G_CreateGeometryFromJson(tmp->value);
+  else
+    geometry=createGeometryFromWFS(conf,tmp->value);
+  res=OGR_G_ConvexHull(geometry);
+  tmp1=getMapFromMaps(outputs,"Result","mimeType");
+  if(strncmp(tmp1->value,"application/json",16)==0){
+    addToMap(outputs->content,"value",OGR_G_ExportToJson(res));
+    addToMap(outputs->content,"mimeType","text/plain");
+  }
+  else{
+    addToMap(outputs->content,"value",OGR_G_ExportToGML(res));
+  }
+  outputs->next=NULL;
+  OGR_G_DestroyGeometry(geometry);
+  OGR_G_DestroyGeometry(res);
+  return SERVICE_SUCCEEDED;
+}
+}}}
+
+This new code is exactly the same as for the Boundary Service. The only thing we modified is the line where the OGR_G_ConvexHull function is called (rather than the OGR_G_GetBoundary you used before). It is better to not copy and paste the whole function and find a more generic way to define your new Services as the function body will be the same in every case. The following generic function is proposed to make things simpler :
+
+{{{
+#!c
+int applyOne(maps*& conf,maps*& inputs,maps*& outputs,OGRGeometryH (*myFunc) (OGRGeometryH)){
+  OGRGeometryH geometry,res;
+  map* tmp=getMapFromMaps(inputs,"InputPolygon","value");
+  if(tmp==NULL)
+    return SERVICE_FAILED;
+  map* tmp1=getMapFromMaps(inputs,"InputPolygon","mimeType");
+  if(strncmp(tmp1->value,"application/json",16)==0)
+    geometry=OGR_G_CreateGeometryFromJson(tmp->value);
+  else
+    geometry=createGeometryFromWFS(conf,tmp->value);
+  res=(*myFunc)(geometry);
+  tmp1=getMapFromMaps(outputs,"Result","mimeType");
+  if(strncmp(tmp1->value,"application/json",16)==0){
+    addToMap(outputs->content,"value",OGR_G_ExportToJson(res));
+    addToMap(outputs->content,"mimeType","text/plain");
+  }
+  else{
+    addToMap(outputs->content,"value",OGR_G_ExportToGML(res));
+  }
+  outputs->next=NULL;
+  OGR_G_DestroyGeometry(geometry);
+  OGR_G_DestroyGeometry(res);
+  return SERVICE_SUCCEEDED;
+}
+}}}
+
+Then, a function pointer called myFunc rather than the full function name can be used. This way we can re- implement our Boundary Service this way :
+
+{{{
+#!c
+int Boundary(maps*& conf,maps*& inputs,maps*& outputs){
+  return applyOne(conf,inputs,outputs,&OGR_G_GetBoundary);
+}
+}}}
+
+Using this applyOne local function defined in the service.c source code, we can define other Services this way :
+
+{{{
+#!c
+int ConvexHull(maps*& conf,maps*& inputs,maps*& outputs){
+  return applyOne(conf,inputs,outputs,&OGR_G_ConvexHull);
+}
+int Centroid(maps*& conf,maps*& inputs,maps*& outputs){
+  return applyOne(conf,inputs,outputs,&MY_OGR_G_Centroid);
+}
+}}}
+
+The genericity of the applyOne function let you add two new Services in your ZOO Services Provider : ConvexHull and Centroid.
+
+Note that you should define MY_OGR_Centroid function before the Centroid one as OGR_G_Centroid don't return a geometry object but set the value to an already existing one and support only Polygon as input, so to ensure we use the ConvexHull for MultiPolygon. So please use the code bellow :
+
+{{{
+#!c
+  OGRGeometryH MY_OGR_G_Centroid(OGRGeometryH hTarget){
+  OGRGeometryH res;
+  res=OGR_G_CreateGeometryFromJson("{\"type\": \"Point\", \"coordinates\": [0,0] }");
+  OGRwkbGeometryType gtype=OGR_G_GetGeometryType(hTarget);
+  if(gtype!=wkbPolygon){
+    hTarget=OGR_G_ConvexHull(hTarget);
+  }
+  OGR_G_Centroid(hTarget,res);
+  return res;
+}
+}}}
+
+To deploy your Services, you only have to copy the Boundary.zcfg metadata file from your cgi-env directory as ConvexHull.zcfg and Centroid.zcfg. Then, you must rename the Service name on the first line to be able to run and test the Execute request in the same way you did before. You only have to set the Identifier value to ConvexHull or Centroid in your request depending on the Service you want to run.
+
+Note here that the GetCapabilities and DescribeProcess requests will return odd results as we didn't modified any metadata informations, you can edit the .zcfg files to set correct values. By the way it can be used for testing purpose, as the input and output get the same name and default/supported formats.
+
+=== Python Version ===
+
+{{{
+#!python
+def ConvexHull(conf,inputs,outputs):
+    if inputs["InputPolygon"]["mimeType"]=="application/json":
+        geometry=osgeo.ogr.CreateGeometryFromJson(inputs["InputPolygon"]["value"])
+    else:
+        geometry=createGeometryFromWFS(inputs["InputPolygon"]["value"])
+    rgeom=geometry.ConvexHull()
+    if outputs["Result"]["mimeType"]=="application/json":
+        outputs["Result"]["value"]=rgeom.ExportToJson()
+        outputs["Result"]["mimeType"]="text/plain"
+    else:
+        outputs["Result"]["value"]=rgeom.ExportToGML()
+    geometry.Destroy()
+    rgeom.Destroy()
+    return 3
+}}}
+
+Once again, you can easily copy and paste the function for Boundary and simply modify the line where the Geometry method was called. Nevertheless, as we did for the C language we will give you a simple way to get things more generic.
+
+First of all, the first step which consists in extracting the InputPolygon Geometry as it will be used in the same way in each Service functions, so we will first create a function which will do that for us. The same thing can also be done for filling the output value, so we will define another function to do that automaticaly. Here is the code of this two functions (extractInputs and outputResult) :
+
+{{{
+#!python
+def extractInputs(obj):
+    if obj["mimeType"]=="application/json":
+        return osgeo.ogr.CreateGeometryFromJson(obj["value"])
+    else:
+        return createGeometryFromWFS(obj["value"])
+    return null
+
+def outputResult(obj,geom):
+    if obj["mimeType"]=="application/json":
+        obj["value"]=geom.ExportToJson()
+        obj["mimeType"]="text/plain"
+    else:
+        obj["value"]=geom.ExportToGML()
+}}}
+
+We can so minimize the code of the Boundary function to make it simplier using the following function definition :
+
+{{{
+#!python
+def Boundary(conf,inputs,outputs):
+    geometry=extractInputs(inputs["InputPolygon"])
+    rgeom=geometry.GetBoundary()
+    outputResult(outputs["Result"],rgeom)
+    geometry.Destroy()
+    rgeom.Destroy()
+    return 3
+}}}
+
+Then definition of the ConvexHull and Centroid Services can be achieved using the following code :
+
+{{{
+#!python
+def ConvexHull(conf,inputs,outputs):
+    geometry=extractInputs(inputs["InputPolygon"])
+    rgeom=geometry.ConvexHull()
+    outputResult(outputs["Result"],rgeom)
+    geometry.Destroy()
+    rgeom.Destroy()
+    return 3
+
+def Centroid(conf,inputs,outputs):
+    geometry=extractInputs(inputs["InputPolygon"])
+    if geometry.GetGeometryType()!=3:
+        geometry=geometry.ConvexHull()
+    rgeom=geometry.Centroid()
+    outputResult(outputs["Result"],rgeom)
+    geometry.Destroy()
+    rgeom.Destroy()
+    return 3
+}}}
+
+Note, that in Python you also need to use ConvexHull to deal with MultiPolygons.
+
+You must now copy the Boundary.zcfg file as we explained for the C version in ConvexHull.zcfg and Centroid.zcfg respectively and then, use make install command to re-deploy and test your Services Provider.
+
+== Create the Buffer Service ==
+
+We can now work on the Buffer Service, which takes more arguments than the other ones. Indeed, the code is a bit different from the one used to implement the Boundary, ConvexHull and Centroid Services.
+
+The Buffer service also takes an input geometry, but uses a BufferDistance parameter. It will also allow you to define LitteralData block as the BufferDistance will be simple integer value. The read access to such kind of input value is made using the same function as used before.
+
+=== C Version ===
+
+If you go back to the first Boundary Service source code, you should not find the following very complicated. Indeed, you simply have to add the access of the BufferDistance argument and modify the line whenthe OGR_G_Buffer must be called (instead of OGR_G_GetBoundary). Here is the ful lcode :
+
+{{{
+int Buffer(maps*& conf,maps*& inputs,maps*& outputs){
+  OGRGeometryH geometry,res;
+  map* tmp1=getMapFromMaps(inputs,"InputPolygon","value");
+  if(tmp==NULL)
+    return SERVICE_FAILED;
+  map* tmp1=getMapFromMaps(inputs,"InputPolygon","mimeType");
+  if(strncmp(tmp->value,"application/json",16)==0)
+    geometry=OGR_G_CreateGeometryFromJson(tmp->value);
+  else
+    geometry=createGeometryFromWFS(conf,tmp->value);
+  int bufferDistance=1;
+  tmp=getMapFromMaps(inputs,"BufferDistance","value");
+  if(tmp!=NULL)
+    bufferDistance=atoi(tmp->value);
+  res=OGR_G_Buffer(geometry,bufferDistance,30);
+  tmp1=getMapFromMaps(outputs,"Result","mimeType");
+  if(strncmp(tmp1->value,"application/json",16)==0){
+    addToMap(outputs->content,"value",OGR_G_ExportToJson(res));
+    addToMap(outputs->content,"mimeType","text/plain");
+  }
+  else{
+    addToMap(outputs->content,"value",OGR_G_ExportToGML(res));
+  }
+  outputs->next=NULL;
+  OGR_G_DestroyGeometry(geometry);
+  OGR_G_DestroyGeometry(res);
+  return SERVICE_SUCCEEDED;
+}
+}}}
+
+The new code must be inserted in your service.c file and need to be recompiled and replace the older version of your ZOO Service Provider in the /usr/lib/cgi-bin/ directory. You must of course place the corresponding ZOO Metadata File in the same directory.
+
+As we explained before, ZOO Kernel is permissive in the sense that you can pass more arguments than defined in you zcfg file, so let's try using a copy of the Boundary.zcfg file renamed as Buffer.zcfg and containing the Buffer identifier. Then, please test your service using an Execute request as you did before. You will obtain the buffer result in a ResponseDocument.
+
+You may have noted that the above code check if a BufferDistance input was passed to the service. If not, we will use 1 as the default value, which explains why you do not have to use one more input to your previous queries.
+
+You can change the BufferDistance value used by your Service to compute Buffer of your geometry by adding it to the DataInputs value in your request. Note that using KVP syntaxe, each DataInputs are separated by a semicolon.
+
+So, the previous request :
+
+{{{
+DataInputs=InputPolygon=Reference@xlink:href=http%3A%2F%2Flocalhost%3A8082%2Fgeoserver%2Fows%3FSERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dtopp %3Astates%26SRS%3DEPSG%3A4326%26FeatureID%3Dstates.15
+}}}
+
+Can now be rewritten this way :
+
+{{{
+DataInputs=InputPolygon=Reference@xlink:href=http%3A%2F%2Flocalhost%3A8082%2Fgeoserver%2Fows%3FSERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dtopp %3Astates%26SRS%3DEPSG%3A4326%26FeatureID%3Dstates.15;BufferDistance=2
+}}}
+
+Setting BufferDistance value to 2 would give you a different result, then don't pass any other parameter as we defined 1 as the default value in the source code.
+
+Here you can find the same query in XML format to use from the http://localhost/test_services.html HTML form :
+
+{{{
+#!xml
+<wps:Execute service="WPS" version="1.0.0" xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 ../wpsExecute_request.xsda">
+ <ows:Identifier>Buffer</ows:Identifier>
+ <wps:DataInputs>
+  <wps:Input>
+   <ows:Identifier>InputPolygon</ows:Identifier>
+   <ows:Title>Playground area</ows:Title>
+   <wps:Reference xlink:href="http://localhost:8082/geoserver/ows/?SERVICE=WFS&amp;REQUEST=GetFeature&amp;VERSION=1.0.0&amp;typename=topp:states&amp;SRS=EPS
+G:4326&amp;FeatureID=states.15"/>
+  </wps:Input>
+  <wps:Input>
+   <ows:Identifier>BufferDistance</ows:Identifier>
+   <wps:Data>
+    <wps:LiteralData uom="degree">2</wps:LiteralData>
+   </wps:Data>
+  </wps:Input>
+ </wps:DataInputs>
+ <wps:ResponseForm>
+  <wps:ResponseDocument>
+   <wps:Output>
+    <ows:Identifier>Buffer</ows:Identifier>
+    <ows:Title>Area serviced by playground.</ows:Title>
+    <ows:Abstract>Area within which most users of this playground will live.</ows:Abstract>
+   </wps:Output>
+  </wps:ResponseDocument>
+ </wps:ResponseForm>
+</wps:Execute>
+}}}
+
+=== Python Version ===
+
+As we already defined the utility functions createGeometryFromWFS and outputResult, the code is as simple as this :
+
+{{{
+#!python
+def Buffer(conf,inputs,outputs):
+    geometry=extractInputs(inputs["InputPolygon"])
+    try:
+        bdist=int(inputs["BufferDistance"]["value"])
+    except:
+        bdist=10
+    rgeom=geometry.Buffer(bdist)
+    outputResult(outputs["Result"],rgeom)
+    geometry.Destroy()
+    rgeom.Destroy()
+    return 3
+}}}
+
+We simply added the use of inputs["BufferDistance"]["value"] as arguments of the Geometry instance Buffer method. Once you get this code added to your ogr_ws_service_provider.py file, simply copy it in the ZOO Kernel directory (or type make install from your ZOO Service Provider root directory). Note that you also need the Buffer.zcfg file detailled in the next section.
+
+=== The Buffer MetadataFile file ===
+
+You must add BufferDistance to the Service Metadata File to let clients know that this Service supports this parameter. To do this, please copy your orginal Boundary.zcfg file as Buffer.zcfg and add the following lines to the DataInputs block :
+
+{{{
+[BufferDistance]
+Title = Buffer Distance
+Abstract = Distance to be used to calculate buffer.
+minOccurs = 0
+maxOccurs = 1
+<LiteralData>
+DataType = float
+<Default>
+uom = degree
+value = 10
+</Default>
+<Supported>
+uom = meter
+</Supported>
+</LiteralData>
+}}}
+
+Note that as minOccurs is set to 0 which means that the input parameter is optional and don't have to be passed. You must know that ZOO Kernel will pass the default value to the Service function for an optional parameter with a default value set.
+
+You can get a full copy of the Buffer.zcfg file here :
+
+http://zoo-project.org/trac/browser/trunk/zoo-services/ogr/base-vect-ops/cgi-env/Buffer.zcfg
+
+You can now ask ZOO Kernel for GetCapabilities, DescribeProcess and Execute for the Buffer Service.
+