Operations and response

Operations

The Panorama Rendering API is a REST service that uses basic authentication. The following operations are possible:

• Render, renders an image based on the id of a recording. Request format:

/Render/{recordingId}/?width=<width>&height=<height>&srsName=<srsName>&yaw=<yaw>&pitch=<pitch>&hfov=<hfov>&apiKey=<apiKey>

The Vertical Field of view (VFov) is a result of the other parameters. To achieve a certain VFov a combination of the HFov and the width height ratio can be used. i.e when the requested width and height are equal, the VFov is also equal to the HFov.

• RenderByLocation2D, renders an image based on the nearest recording to a given location. The image is automatically directed horizontally and vertically to the given location. The z system used is automatically related to the coordsystem <srs>. Request format:

/RenderByLocation2D/{srs}/{x|lon}/{y|lat}/?width=<width>&height=<height>&hfov=<hfov>&apiKey=<apiKey>

• RenderByLocation3D, renders an image based on the nearest recording to a given location. The image is automatically directed horizontally and vertically to the given location. The z system used is automatically related to the coordsystem <srs>. Request format:

/RenderByLocation3D/{srs}/{x|lon}/{y|lat}/{z}/?width=<width>&height=<height>&hfov=<hfov>&apiKey=<apiKey>

• RenderByAddress, renders an image based on the nearest most recent recording to a given address location. The image is automatically directed horizontally to the given address location. Request format:

/RenderByAddress/{country}/{address}/?width=<width>&height=<height>&pitch=<pitch>&hfov=<hfov>&apiKey=<apiKey>

• RenderSurface, returns an image of a flat surface as defined by a set of four coordinates, which -as seen from an observer- respectively define the upper left, upper right, lower right and lower left corners of the surface. RenderSurfaceautomatically selects potentially suitable recording location. For more details, see Understanding RenderSurface. Request format:

/RenderSurface/{srs}/{coordinates}/?index=<index>&margin=<margin>&maxElevation=<maxElevation>&apiKey=<apiKey>

• ListByAddress, lists the recordings nearest to a given address location, includes historical recordings. The horizontal direction to the given address location is also returned. The result data is returned in XML format. The output list is ordered according to the distance to the given address location. Request format:

/ListByAddress/{country}/{address}/?IncludeHistoricRecordings=<IncludeHistoricRecordings>&apiKey=<apiKey>

• ListByLocation2D, lists the recordings nearest to a given 2D location, includes historical recordings. The horizontal direction to the given given location is also returned. The result data is returned in XML format. The output list is ordered according to the distance to the given address location. Request format:

/ListByLocation2D/{srs}/{x}/{y}/?IncludeHistoricRecordings=<IncludeHistoricRecordings>&apiKey=<apiKey>

• ListByCoordinates, lists the recordings nearest to a given surface, includes historical recordings. The horizontal direction to the given service is also returned. The result data is returned in XML format. The output list is ordered according to the distance to the given address location.

/ListByCoordinates/{srs}/{coordinates}/?IncludeHistoricRecordings=<IncludeHistoricRecordings>&apiKey=<apiKey>

With the exception of your API Key, parameters after the question mark “?” may be omitted. The default values as listed on the right under "Overview of parameters" will then be used instead.

Understanding RenderSurface

Selection of Suitable Recording Location

RenderSurface returns an orthogonal view that appears to be taken exactly in front of a specified surface, from a source recording location which was not. The quality of the output depends on the recording location that was used; steeper angles will negatively influence results.

RenderSurface considers the following when rendering a building facade:

• It will discount any recording that is not located in front of the surface. Similarly, any recording made too close to a tall building, is discounted.

• The remaining recordings are ordered by an index that represents the match on horizontal angle and distance, as per below image.

1 - Currently surfaces that are virtually completely horizontal, such as roofs or sections of road, are not supported and may result in an error code.

2 - A rectification takes place based on the normal of the surface, where the normal is found by using the first 3 coordinates.

3 - “maxElevation” is used to specify when recordings are deemed too close to be suitable.

In above image we see that various recordings are not suitable for generating a view of the surface. The numbered dots represent recording locations that have been indexed based on their maximum horizontal theoretical image quality.

This figure demonstrates how three fictional recording locations yield varying image resolution potential, as determined by the horizontal angles between the measurement points at the surface centre. Recordings are automatically ordered by this theoretical horizontal image quality.

In general, one can expect index 0 to contain the highest resolution image with the least chance of occlusion. Conversely, higher indexes will produce higher incidence of occlusion and a lower overall resolution. (Note: In figure 1, the default “maxElevation” angle limit forced what would have been index 0 and 1 to be discounted out-of-hand; with a lower building or increased “maxElevation” tolerance this would not have happened).

In this example, for best results, the API user should choose index 3 to get an unobstructed view of the specified surface, as index 0 through 2 contain trees.

Occlusion and High Buildings

Due to the propensity toward occlusion with distance it is not prudent to automatically index recording locations for their quality based on the vertical angle towards the surface; This would prioritize recording locations that are further away, causing lower resolution imagery while also being more likely to produce occlusion.

Instead of taking the elevation angle into account when indexing images, a maximum desired elevation “maxElevation” can be used instead. A default value of 75 degrees is used.

With this knowledge an API user can take two distinct approaches in dealing with “RenderSurface” with regard to tall buildings:

A. Increase the index until no occlusion occurs (trying possibilities #0,#1 and #2, before arriving at #3)

B. Increase the maximum allowed elevation, such that index 0 is as close to the surface as possible, minimizing the chance of occlusion. (Doing so may however severely impact the quality the output image).

The parameters for achieving optimal results vary from situation to situation.

Note that when using source recordings which have a steep angle towards the defined surface, any errors that are present in either the surface coordinates and/or the orientation are amplified. To account for this influence, it may be advisable to specify a margin using the parameter “margin” to offer some required leeway.

Possible error messages

The following error messages may be returned when a call is made toRenderSurface that cannot be completed:

• "There are no recordings that contain the front of the given surface."
  This error indicates there are no (authorized) recordings that are both within 300 metres and can contain the front of the surface.

• "There are no recordings with an acceptable elevation towards the surface (current parameter 'maxElevation={maxElevation}' degrees.)"

  This error can occur for very tall surfaces or those located very high; it can be resolved by increasing the limit on maxElevation

• "The Surface Rendering candidate at (zero based) index {index}does not exist. There are only {maxIndex+1} recordings enumerated within the radius currently defined. Occurs when trying to access an index that doesn’t exist."

  This error indicates that an attempt was made to access an index that did not exist.

• "There are no recordings within the specified distance of{Distance}. (Determined with maxDistanceToHeightRatio='{maxDistanceToHeightRatio}' multiplied by the surface height which was calculated as being: '{surfaceHeight}')"

  This error results when no recordings were within a maximum distance defined as: maximum distance = ( SurfaceHeight × maxDistanceToHeightRatio )

Metadata Pertaining to RenderSurface

The XML and Header output of the RenderSurface method differs from the other methods in that it contains no fields that pertain to the yaw,pitch or roll. Here is the full example output of the call matching that of the url attribute:

<SurfaceRenderingMetaData 
url="https://atlasapi.cyclomedia.com/api/PanoramaRendering/RenderSurface/28992/146146.237900;420960.062190;15.5987216758;146151.119766;420960.550906;15.4933704670;146151.123472;420960.639873;10.4842588117;146146.163319;420960.143950;10.5556708197/?apiKey=abcdef12345&format=xml"
recording-id="5D35XF24"
recording-date="2015-02-18T10:40:41.98+00:00"
width="666"
height="680"
recording-location-lon-precision="0.026"
recording-location-lat-precision="0.018"
recording-location-height-precision="0.023"
recording-location-groundleveloffset="2.01"
recording-location-srs="EPSG:28992"
recording-location-x="146146.039"
recording-location-y="420954.089"
recording-location-z="5.152"/>

Response format

The response of all methods is a JPG image for the runtime rendered image, if not specified otherwise. Metadata is returned in HTTP response headers, for example:

Recording-Id: 5D0G4E8O
Recording-Date: 2011-09-15T12:48:07.5900000+02:00
Render-Width: 1024
Render-Height: 786
Render-FocalLength: 512.000
Render-HFov: 90.000
Render-VFov: 75.018
Render-Yaw: 0.000
Render-Pitch: 0.000
Render-Roll: 0.000
RecordingLocation-SrsBase: EPSG:4258
RecordingLocation-Longitude: 5.089819277
RecordingLocation-LongitudePrecision: 0.008
RecordingLocation-Latitude: 52.109259974
RecordingLocation-LatitudePrecision: 0.004
RecordingLocation-Height: 46.918
RecordingLocation-HeightPrecision: 0.009
RecordingLocation-GroundLevelOffset: 2.01
RecordingLocation-YawPrecision: 0.0075

Error response format

On input or processing error cases an XML error message is returned.

ResponseHeader:

Content-Type: application/xml; charset=utf-8

ResponseBody:

<Fault xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <detail>The specified address was not found by ...</detail>
  <faultcode>404</faultcode>
  <faultstring>NotFound</faultstring>
</Fault>

HTTP response codes:

The normal behaviour of REST web services is, to return HTTP status codes that correspond to the situation, if appropriate. This is also the case for this REST web service.

It is however possible to override this behaviour to make some integrations easier/possible.

When “ReturnHttpErrors=0” is defined, the service itself will always return a 200 response code. The original designated HTTP response code is always reflected in the “faultcode” field of the XML error message.