Envinsa. Coordinate Geometry Service Reference

Transcription

1 Envinsa Coordinate Geometry Service Reference

2 Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of Pitney Bowes MapInfo Corporation, One Global View, Troy, New York Pitney Bowes MapInfo Corporation. All rights reserved. MapInfo, the MapInfo logo and Envinsa are trademarks of Pitney Bowes MapInfo Corporation and/or its affiliates. Corporate Headquarters: Phone: Fax: Sales: Government Sales: Technical Support: UK and EMEA Headquarters: Phone: Fax: Technical Support: Asia Pacific Headquarters: Phone: Fax: Technical Support: Contact information for all Pitney Bowes MapInfo offices is located at: Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark. April 23, 2008

3 Table of Contents Chapter 1: Introduction What is the Coordinate Geometry Service? Coordinate Geometry Service Functionality Point-to-Point Distance Calculations Point-in-Region Calculations Geometric Measurements Buffer Calculations Chapter 2: Coordinate Geometry Capabilities Calculating a Point-to-Point Distance Inputs and Behaviors Output Java Code Sample NET Code Sample XML Sample Determining if a Point is in a Region Inputs and Behaviors Handling the Distance Unit Output Java Code Sample NET Code Sample XML Sample Calculating Perimeter, Area, or Volume Inputs and Behaviors Handling the Distance Unit Output Java Code Sample NET Code Sample XML Sample Buffering a Geometry Inputs and Behaviors Output Resolution Examples

4 Distance Examples Java Code Sample XML Sample Chapter 3: Configuration Configuration

5 Introduction 1 Welcome to the Envinsa Platform Web Services. This guide provides descriptions and examples for the developer who is writing applications that will access the Coordinate Geometry Service. The Coordinate Geometry Service performs a collection of calculations on geographic data. In this section: What is the Coordinate Geometry Service? Coordinate Geometry Service Functionality

6 Coordinate Geometry Service Functionality What is the Coordinate Geometry Service? The Coordinate Geometry Service (Cogo) performs geometric calculations and measurements for geographical data represented in Geography Markup Language (GML). The Coordinate Geometry Service computes containment and distance values for geometries, returns a straight-line distance between two points (2D and 3D), verifies a point position relative to a region, returns a buffered region around or inside a geometry, and calculates measurements for perimeter and area, and for the volume formed by projecting a 2D region onto the X/Y plane (supported geometries include: Polygon, CircleByCenterPoint, CircularArc, and Ellipse). Coordinate Geometry Service Functionality The Coordinate Geometry Service has four main operations: Point-to-point distance calculations. Point-in-region calculations. Geometric measurement calculations. Buffer calculations. Point-to-Point Distance Calculations Given a distance unit, two GML points, and a coordinate system, the Coordinate Geometry Service returns a straight-line distance between the two points. Both spherical and Cartesian calculations are supported. (Spherical calculation can be made for 3D point-to-point distance calculations.) If one or both of the points uses a spherical coordinate system (for example, Latitude/Longitude), a spherical calculation is performed. If both points use a Cartesian coordinate system (for example, EPSG:32617), either a Cartesian or a spherical calculation can be performed. The following section shows you how to use this capability: Calculating a Point-to-Point Distance in Chapter 2 on page 10 One scenario in which you would use this type of calculation is to obtain the distance between two airports to determine the flight path distance. Since this distance is based on the curvature of the Earth, a spherical distance is needed to get the distance from one airport to the other. 6

7 Chapter 1: Introduction Point-in-Region Calculations Given a GML point, a GML polygon, and a coordinate system, a point-in-region calculation returns "inside" if the point is inside the polygon, "outside" if the point is outside the polygon, or "boundary" if the point is on the boundary of the polygon. This calculation supports circle, circular-arc, ellipse, and polygon geometries: The following section shows you how to use this capability: Determining if a Point is in a Region in Chapter 2 on page 12 One scenario in which you would use this type of calculation is to obtain whether a city airport is within the city limits. Geometric Measurements Given a two dimension or three dimension GML geometry (Polygon, CircleByCenterPoint, CircularArc, or Ellipse), the Coordinate Geometry Service can return the geometry s perimeter or area, or the volume formed by projecting the geometry onto the X/Y plane. The following section shows you how to use this capability: Calculating Perimeter, Area, or Volume in Chapter 2 on page 15 One scenario in which you would use this type of calculation is to obtain the perimeter and area of a piece of land for a potential real estate acquisition. Coordinate Geometry Service Reference 7

8 Coordinate Geometry Service Functionality Buffer Calculations Given a GML geometry (Point, LineString, Polygon, CircleByCenterPoint, CircularArc, or Ellipse), the Coordinate Geometry Service can return a buffered region either around or inside the geometry. The following section shows you how to use this capability: Buffering a Geometry in Chapter 2 on page 19 One scenario in which you would use this type of calculation is to obtain an area around a route, which you can then search to find gas stations or ATMs along the route. 8

9 Coordinate Geometry Capabilities 2 Before you create an application that uses Coordinate Geometry Service functionality, it s helpful to understand basic concepts and how these concepts are implemented in the Coordinate Geometry Service. This section describes how to develop and use the capabilities of the Coordinate Geometry Service. In this section: Calculating a Point-to-Point Distance Determining if a Point is in a Region Calculating Perimeter, Area, or Volume Buffering a Geometry

10 Calculating a Point-to-Point Distance A Coordinate Geometry point-to-point distance request obtains the distance between two points (for example, two airports or cities). Both spherical and Cartesian calculations are supported. If one or both of the points uses a spherical coordinate system (for example, Latitude/Longitude), a spherical calculation is performed. If both points use a Cartesian coordinate system (for example, EPSG:32617), either a Cartesian or a spherical calculation can be performed. Inputs and Behaviors There are five key pieces of information for a point-to-point distance request: Input Required Description Calculation ID Yes The calculation identifier when multiple calculations are performed in a single request. Type of Distance Calculation Yes The type of point-to-point distance calculation to be performed (spherical or Cartesian). Unit No The unit of measure in which the distance is to be returned. The available units are: kilometer (KM), mile (MI), meter (M), foot (FT), and yard (YD). The default unit for point-to-point distance is KM if not specified in the request. Start Point and End Point Yes The start and end points for the point-to-point distance calculation. Dimension No The number of dimensions: 2 or 3. The default is 2. If 3D points are given, the 3D spherical distance can be calculated. For Cartesian distance calculations, the number of dimensions is always 2. Output The response to a point-to-point distance request is composed of two sections: Output Unit of Measure Distance Value Description The measurement unit of the calculated distance, as specified in the request. The distance from the start point to the end point specified in the request. 10

11 Chapter 2: Coordinate Geometry Capabilities Java Code Sample The following example performs a spherical point-to-point distance calculation in meters between the two points (spoint and epoint). In the request the distance calculation type is set to spherical (DISTANCE_TYPE_SPHERICAL) and the unit of measure is set to meters (DistanceUnit.M). public CogoRequest createspointtopointdistance() { //create a cogo request CogoRequest request = new CogoRequest("Cogo", "4.0", "R1"); Point spoint = GeometryUtils.newPoint( , , null); Point epoint = GeometryUtils.newPoint( , , null); RequestCalculation calculation = new RequestCalculation("POINTTOPOINTDISTANCE"); PointToPointDistance ptp = new PointToPointDistance(spoint, epoint); ptp.setdistancetype(pointtopointdistance.distance_type_spherical); ptp.setdistanceunit(distanceunit.m); calculation.setpointtopointdistance(ptp); request.addrequestcalculation(calculation); } return request;.net Code Sample The following example performs a spherical point-to-point distance calculation between the two points (spoint and epoint). In the request the distance calculation type is set to spherical (DistanceCalculationType.spherical) and the number of calculations to be performed is specified as two (new RequestCalculation[1]). You can perform more than one calculation in a request. private static Request newpointtopointdistancerequest() { CogoRequest drr = new CogoRequest(); drr.requestid = "1"; //Cogo request include one or multiple calculations RequestCalculation[] rc = new RequestCalculation[1]; rc[0] = new RequestCalculation(); rc[0].id ="C1"; //specify start and end points to calculate the distance for Point spoint = GeometryUtils.newPoint( , , "EPSG:4326"); Point epoint = GeometryUtils.newPoint( , , "EPSG:4326"); PointToPointDistance ptp = new PointToPointDistance(); ptp.startpoint = spoint; ptp.endpoint = epoint; ptp.distancetype = DistanceCalculationType.spherical; rc[0].cogocalculation = ptp; drr.requestcalculation = rc; return drr; Coordinate Geometry Service Reference 11

12 Determining if a Point is in a Region } XML Sample The following example performs a Cartesian point-to-point distance calculation in kilometers between the two points (startpoint and endpoint). In the request the distance calculation type is set to Cartesian (distancetype="cartesian") and the unit of measure is set to kilometers (distanceunit="km"). <_RequestParameters xsi:type="ns3:cogorequesttype" xmlns:ns3=" <ns3:calculation ID="POINTTOPOINTDISTANCE"> <ns3:pointtopointdistance distancetype="spherical" distanceunit="m"> <ns3:startpoint> <ns4:pos dimension="2" xmlns:ns4=" </ns4:pos> </ns3:startpoint> <ns3:endpoint> <ns5:pos dimension="2" xmlns:ns5=" </ns5:pos> </ns3:endpoint> </ns3:pointtopointdistance> </ns3:calculation> </_RequestParameters> Determining if a Point is in a Region A Coordinate Geometry point-in-region request obtains a point s position relative to a region. Given a GML point, a GML polygon, and a coordinate system, it returns "inside" if the point is inside the polygon, "outside" if the point is outside the polygon, or "boundary" if the point is on the boundary of the polygon. This calculation supports circle, circular-arc, ellipse, and polygon geometries. Inputs and Behaviors There are four key pieces of information for a point-in-region request: Input Required Description Calculation ID Yes The calculation identifier when multiple calculations are performed in a single request. Tolerance No The allowance or accuracy for the calculation. The tolerance determines the resolution of the polygon. The smaller the tolerance the more points will be used to construct the polygon resulting in more accurate results. Point Yes The point whose position relative to the region is being determined. 12

13 Chapter 2: Coordinate Geometry Capabilities Input Required Description Geometry Yes The geometry being used to determine the point in region. This can be a Polygon, CircleByCenterPoint, CircularArc, or Ellipse. Handling the Distance Unit In order to determine the position of a point relative to a geometric shape (circle, circular arc sector, or ellipse), the shape geometry is expanded to a polygon where the formula depends on a distance unit. The position of the point is then checked against the polygon. This operation also depends on the tolerance. By modifying the distance unit and the tolerance, you may produce different containment results. Distance units are specified through the unit of measure for any linear value (specifically, radius and axis). The Coordinate Geometry Service handles various geometries differently depending on the geometry complexity and number of possible units of measure. For the circle geometry the unit of measure specified for the circle center point will be used as the distance unit. For the ellipse and circular arc geometries, the units of measure for the major and minor axis, or the inner and outer radius, must be the same and are used as the distance unit. Output The response to a point-in-region request is composed of one section: Output Containment Description The position of the point relative to the region: inside, outside, or boundary. Java Code Sample public CogoRequest createspointingeometry() { CogoRequest request = new CogoRequest("Cogo", "4.0", "R1"); //create a cogo request Point point = GeometryUtils.newPoint( , , "EPSG:4326"); CircleByCenterPoint circle = GeometryUtils.getXLSGMLFactory().newCircleByCenterPoint(); circle.setcenter(point.getcoord()); circle.setradius(new Length("M", 100)); RequestCalculation[] calculations = new RequestCalculation[1]; calculations[0] = new RequestCalculation("POINTINGEOMETRY"); PointInGeometry pig = new PointInGeometry(point); pig.setcirclebycenterpoint(circle); pig.settolerance( ); Coordinate Geometry Service Reference 13

14 Determining if a Point is in a Region calculations[0].setpointingeometry(pig); request.setrequestcalculation(calculations); } return request;.net Code Sample private static RequestCalculation newpointincirclecalculation(string calculationid, Point spoint) { RequestCalculation rc = new RequestCalculation(); rc.id =calculationid; PointInGeometry pic = new PointInGeometry(); pic.tolerance = ; //set the reference point pic.point = spoint; //create the center point of the circle Point cpoint = GeometryUtils.newPoint( , , "EPSG:4326"); //create the circle by center point used to verify the containment of the point CircleByCenterPoint circle = GeometryUtils.newCircleByCenterPoint(cPoint, 10, DistanceUnitType.MI); pic.circlebycenterpoint = circle; rc.cogocalculation = pic; return rc; } XML Sample <_RequestParameters xsi:type="ns3:cogorequesttype" xmlns:ns3=" <ns3:calculation ID="POINTINGEOMETRY"> <ns3:pointingeometry tolerance="1.0e-5"> <ns4:point srsname="epsg:4326" xmlns:ns4=" <ns4:pos dimension="2"> </ns4:pos> </ns4:point> <ns6:circlebycenterpoint interpolation="circulararccenterpointwithradius" numarc="1" xmlns:ns6=" <ns6:pos dimension="2"> </ns6:pos> <ns6:radius uom="m">100.0</ns6:radius> </ns6:circlebycenterpoint> </ns3:pointingeometry> </ns3:calculation> </_RequestParameters> 14

15 Calculating Perimeter, Area, or Volume Chapter 2: Coordinate Geometry Capabilities The Coordinate Geometry measurement request obtains the perimeter, area, or volume formed by projecting onto the X/Y plane, of a given GML geometry. These calculations support circle, circulararc, ellipse, and polygon geometries. Inputs and Behaviors There are five key pieces of information for a measurement calculation request: Input Required Description Calculation ID Yes The calculation identifier when multiple calculations are performed in a single request. Type of Calculation Yes The type of measurement calculation being performed (perimeter, area, or volume). Distance Unit No The type of unit used for the calculation. The available units are: kilometer (KM), mile (MI), meter (M), foot (FT), and yard (YD). For more information, see Handling the Distance Unit on page 15. Geometry Yes The geometry on which the measurement calculation is performed. Dimension No The number of dimensions: 2 or 3. The default is 2. You can specify a dimension only when requesting a perimeter calculation for a geometry that has 3D coordinates. In all other cases, specifying a dimension results in an error. Handling the Distance Unit The distance unit may be specified in the request. If this is not specified then a default value is used. The default value for measurement calculations is MI. For perimeter calculations, the unit of measure returned is the same as in the request (for example, MI). For area calculations, the unit of measure returned is the specified unit squared (for example, Square_Mile). For volume calculations, the unit of measure returned is the specified unit cubed (for example, Cubic_Mile). Output The response to a measurement calculation request is composed of two main sections: Output Unit of Measure Description The returned unit of measure for the measurement calculation specified in the request. For perimeter calculations, the unit of measure returned is the same as in the request (for example, MI). For area calculations, the unit of measure returned is the specified unit squared (for example, Square_Mile). For volume calculations, the unit of measure returned is the specified unit cubed (for example, Cubic_Mile). Coordinate Geometry Service Reference 15

16 Calculating Perimeter, Area, or Volume Output Measurement Value Description The resulting value for a perimeter, area, or volume calculation. 16

17 Chapter 2: Coordinate Geometry Capabilities Java Code Sample public CogoRequest createsvolumemeasurement() { CogoRequest request = new CogoRequest("Cogo", "4.0", "R1"); //create a Measurement Volume Request RequestCalculation[] calculations = new RequestCalculation[1]; calculations[0] = new RequestCalculation("VOLUME"); MeasurementCalculation volume = new MeasurementCalculation(); //distanceunit is set by default to MI. Sets the Measurement calculation to Volume volume.setmeasurement(measurementcalculation.measurement_volume); //sets the geometry Polygon polygon = null; try { //creates an instance of the xls factory xlsgmlfactory xlsfactory = (xlsgmlfactory)xlsgmlfactory.newinstance(gmlfactory.xls); //creates the geometry ( Polygon ) DirectPosition[] crdext = new DirectPosition[5]; crdext[0] = xlsfactory.newdirectposition(" "); crdext[1] = xlsfactory.newdirectposition(" "); crdext[2] = xlsfactory.newdirectposition(" "); crdext[3] = xlsfactory.newdirectposition(" "); crdext[4] = xlsfactory.newdirectposition(" "); LinearRing exterior = xlsfactory.newlinearring(crdext); polygon = xlsfactory.newpolygon(exterior); } catch(exception e) { e.printstacktrace(); } volume.setpolygon(polygon); calculations[0].setmeasurementcalculation(volume); request.setrequestcalculation(calculations); } return request; Coordinate Geometry Service Reference 17

18 Calculating Perimeter, Area, or Volume.NET Code Sample private static Request newmeasurementcalculationrequest() { CogoRequest drr = new CogoRequest(); drr.requestid = "3"; drr.methodname = "perform"; drr.version = "3.5"; RequestCalculation[] rc = new RequestCalculation[1]; rc[0] = new RequestCalculation(); rc[0].id ="C3.0"; //Cogo request include one or multiple calculations MeasurementCalculation mcalc = new MeasurementCalculation(); //specify measurement type: perimeter, area or volume. mcalc.measurementcalculationtype = MeasurementCalculationType.area; //specify the unit of the measurement. For area, the result is //calculated in square units. For volume the result is in cubical units mcalc.distanceunit = DistanceUnitType.MI; //create the polygon used to calculate the area double [,] ext = new double[,]{ {0,0},{- 10,10},{10,50},{50,10},{30,0},{0,0}}; double[][,] ints = new double [1][,]{new double[,] { {0,0},{- 10,10},{10,50}, {0,0} }}; Polygon poly = GeometryUtils.newPolygon(ext, ints, "EPSG:4326"); mcalc.polygon = poly; rc[0].cogocalculation = mcalc; } drr.requestcalculation = rc; return drr; XML Sample <_RequestParameters xsi:type="ns9:cogorequesttype" xmlns:ns9=" <ns9:calculation ID="VOLUME"> <ns9:measurement measurementtype="volume"> <ns10:polygon xmlns:ns10=" <ns10:exterior> <ns10:_ring xsi:type="ns10:linearringtype"> <ns10:pos dimension="3"> </ns10:pos> <ns10:pos dimension="3"> </ns10:pos> <ns10:pos dimension="3"> </ns10:pos> <ns10:pos dimension="3"> </ns10:pos> <ns10:pos dimension="3"> </ns10:pos> </ns10:_ring> </ns10:exterior> </ns10:polygon> </ns9:measurement> </ns9:calculation> </_RequestParameters> 18

19 Chapter 2: Coordinate Geometry Capabilities Buffering a Geometry Buffer calculations allow you to create areas around points, lines, and geometries, which can be used to provide important analysis. For example, a user planning a trip wants to find the best place to fill up with gas. Having created a route of the trip using the Route Service, the Coordinate Geometry Service can be used to create a buffered area by specifying the route geometry and a buffer distance from the route. The Coordinate Geometry Service returns a buffered polygon or multi-polygon that can be used as a search area by the Directory Service to find all the gas stations along the route. Inputs and Behaviors There are four key pieces of information for a measurement calculation request: Input Required Description Calculation ID Yes The calculation identifier when multiple calculations are performed in a single request. Resolution No The buffer's detail level. The higher the resolution the smoother the curves of the buffer. The lower the resolution the more jagged the curves of the buffer. The resolution indicates the number of segments used when creating a 90º curve for the buffer. The resolution must be no less than four (the minimal value to create a meaningful buffer). If no resolution is specified in the request, the default resolution of four is used. For an example, see Resolution Examples on page 20. Distance and Unit Yes The width of the buffer. The Coordinate Geometry Service can buffer the outside and inside of circles, circular arcs, ellipses, and polygons. If the distance is positive, the buffered region will be larger than (outside) the source geometry. If the distance is negative the buffered region will be smaller than (inside) the source geometry. Point and line geometries only support positive buffers. In certain circumstances no buffered region may be returned if a buffer cannot be created based on a given negative distance (specifically, the negative distance is greater than the span or diameter of the geometry). The available units are: kilometer (KM), mile (MI), meter (M), foot (FT), and yard (YD). If no unit is specified in the request, the default unit meter (M) is used. For examples, see Distance Examples on page 21. Coordinate Geometry Service Reference 19

20 Buffering a Geometry Input Required Description Geometry Yes The geometry and spatial reference system to be buffered. Supported geometries include Point, LineString, Polygon, CircleByCenterPoint, CircularArc, and Ellipse. If no spatial reference system is specified in the source geometry, the default WGS84 (srsname = "EPSG:4326") is used. Be aware that some spatial reference systems are either spherical or Cartesian. Spherical calculations measure distance according to the curved surface of the Earth. This means that the distance from the boundary of the source geometry to the boundary of the new buffered object may vary from node to node. Cartesian calculations measure distance on data that has been projected onto a flat, X-Y plane. This produces buffers that are exact in width, as long as the data is not in a Lat/Long projection. Output The response to a buffer request is composed of two main sections: Output Geometry Spatial Reference System Description The buffered region of a point is returned as a polygon. The buffered region of all others may be a polygon or a multi-polygon depending on the complexity of the geometry and the resolution required. The buffered region is always in two dimensions. The geometry of the buffered region is in the same coordinate system as of the source geometry. If there is no srsname specified in the source geometry, the default WGS84 (srsname = "EPSG:4326") is used. Resolution Examples The following illustrations show the effect of changing the input value for resolution. Changing Resolution: The image on the left has a resolution of four, the image on the right has a resolution of six. Notice that the right image has a smoother curve. 20

21 Chapter 2: Coordinate Geometry Capabilities Distance Examples The following illustrations show the effects of different input values for distance. Changing distance: The image on the left is buffered by 25 meters; the image on the right is buffered by 50 meters. Notice that the right image has a larger buffered area. Positive and negative distance: The image on the left is buffered by 25 meters (outside the polygon), the image on the right is buffered by -25 meters (inside the polygon). Java Code Sample public CogoRequest createsbuffer() { //creates a cogo request CogoRequest request = new CogoRequest("Cogo", "4.0", "R1"); //creates a new Point Point point = GeometryUtils.newPoint( , , "EPSG:4326"); //creates a CircleByCenterPoint CircleByCenterPoint circle = GeometryUtils.getXLSGMLFactory().newCircleByCenterPoint(); circle.setcenter(point.getcoord()); Coordinate Geometry Service Reference 21

22 Buffering a Geometry circle.setradius(new Length("M", 100)); //creates a new calculation type ( buffer ) RequestCalculation[] calculations = new RequestCalculation[1]; calculations[0] = new RequestCalculation("BUFFER"); //creates a new buffer Buffer buffer = new Buffer(10); buffer.setcirclebycenterpoint(circle); buffer.setresolution(4); calculations[0].setbuffer(buffer); request.setrequestcalculation(calculations); } //returns a CogoRequest return request; XML Sample <_RequestParameters xsi:type="ns3:cogorequesttype" xmlns:ns3=" <ns3:calculation ID="BUFFER"> <ns3:buffer distance="10.0"> <ns4:circlebycenterpoint interpolation="circulararccenterpointwithradius" numarc="1" xmlns:ns4=" <ns4:pos dimension="2"> </ns4:pos> <ns4:radius uom="m">100.0</ns4:radius> </ns4:circlebycenterpoint> </ns3:buffer> </ns3:calculation> </_RequestParameters> 22

23 Configuration 3 This section describes the configuration settings you can modify for the Coordinate Geometry Service. In this section: Configuration

24 Configuration The Coordinate Geometry Service has a Tolerance preference that administrators can configure using the Enterprise Manager: Parameter Description Default Value Tolerance The default tolerance setting for point-in-region calculations, used to control the accuracy of the calculation. This tolerance is used if no tolerance value is specified in the request