Mapspace Web Services

Street Services, 360 Panorama images

Overview

Street images are 360º degrees images obtained at ground level allowing the users to see the facades of the buildings. These images need to be treated specially.

The images are projected in a cubic projection, and each file is composed by a determinate number of frames obtained by determinate number of cameras.

Every street picture has a centroid. The coordinates of this point serve as an identifier to every image. This point will be the location of the shoot.

Example of coverage of a set of images:

The cubic image is composed by 6 faces: front (f), back (b), right (r), left (l), up (u) & down (d). The front face will be centered and perpendicular to the car direction driving (direction yaw angle). Each face is composed by ties of 256x256. These tiles are available at several resolutions: Maximum Image resolution, ½ resolution, ¼ resolution and 1/8 resolution. These different scales are called zoom levels and are referenced as: 0,1, 2, 3 and so on if is needed. The minimum resolution is 0 and each face is composed by only one tile of 256x256.

Next picture shows an example of how the street image faces are cut into tiles. The code used to identify the tiles has 3 parts: the zoom level, and a pair of x, y coordinates of the tiles referenced to the upper left corner of the image.

Locating a tile

To find the tile where a particular pixel (of the original street image face) is located at a given zoom level, this formula can be used:

tileX = floor(pixelX / (256 * 2 level))
tileY = floor(pixelY / (256 * 2 level))

And the position of the original pixel within the tile:

Xoffset = (pixelX – tileX * 256 * 2 level) / (256 * 2 level)
Yoffset = (pixelY – tileY * 256 * 2 level) / (256 * 2 level)

All pixel coordinates are referred to the top-left corner of the images.

Image Identifier

The identifier of any Street image, follows this structure:

CXXXX.XXXXXX_YY.YYYYYY_YYMMDD

Where:

The first character (C) indicates ‘Cubic’ projection.

Characters from position 2 to 12 (XXXX.XXXXXX) represent the longitude of the photo center in LAT/LON WGS84.

The characters from position 14 to 22 (YY.YYYYYY) represent the latitude of the centre of the photo in LAT/LON WGS84.

The final 6 characters (YYMMDD) represent the date in which the photography was taken, (YY=year, MM=month, DD=day).

Example:

The image with this Id: C+018.075481_59.285323_160807 has its center located at Longitude 18.075481, Latitude 59.285323 and was taken on August, 7; 2016

INWFSProxyStreet

The INWFSProxyStreet service is a web service based in the WFS standard protocol for serving vector information.

Mapspace offers the WFS service to allow users to access to vector information related with the Street Image centroids and metadata information following OGC's regulation and directives.

The service uses the http protocol with the parameters normalized by OGC, which define version, type of request, coordinate system, bounding box, etc.

The service supports several input projection systems, but vector information will provided on EPSG:4326 projection.

The WFS supported versions are 1.0.0 & 1.1.0.

Connection

To connect to the Mapspace INWFSProxyStreet service from a GIS client, it is necessary to setup the following URL:

http://your.mapspace.com/mapSvcs/INWFSProxyStreet?REQUEST=GetCapabilities&SERVICE=WFS&ServiceName=WFS&version=1.1.0&userkey=****************

In this request, userkey string must be replaced by the unique platform access key provided by Field Group.

GetCapabilities returns information about available features, capabilities and spatial operators.

In order to support SSL web protocol (HTTPS) it has been added a new clone service on this URL:

https://your.mapspace.com/mapSvcs/INWFSProxyStreetSSL?REQUEST=GetCapabilities&SERVICE=WFS&ServiceName=WFS&version=1.1.0&userkey=****************

Parameters

Parameters defined by OGC standard are:

  • Version [mandatory]: This parameter is the WFS version that is used for this request. Only two values are accepted in the current API version:
    • 1.0.0
    • 1.1.0
  • Request [mandatory]: Possible values are:
    • GetCapabilites: used to obtain the web services descriptor xml file
    • DescribeFeatureType: returns the feature descriptor xml file.
    • GetFeature: used to retrieving a feature query.
  • Service [mandatory]: The service name: WFS
  • Typename: mandatory for GetFeature and DescribeFeatureType requests. It is the name of the feature layer provided by the service. Street images will be provided by the name of ‘panorama’.
  • Userkey [mandatory]: User’s key for authentication purposes. This key is unique for each client and must be requested from Field Group.
  • Bbox [optional]: Optional for GetFeature request. It defines the bounding box extent of the query.
  • SrsName [optional]: it defines the projection system of the input information (i.e. bbox).

Usage

The result of the GetCapabilities & DescribeFeatureType will be a Xml file according the OGC standard definition.

The output of GetFeature request is a Gml file with next parameters:

  • Geometry: location of Street image centroid (x,y,z). Provided in EPSG:4326 projection
  • Pk_panorama: Street image identifier.
  • Url: This is the link url for the load of the single Street image in a web browser.
  • Direction_yaw: This is the car direction angle to the North in degrees.
  • Tile_size: this is the tile size (x & y value) of all tiles in each cubic face
  • Zoom_levels: Number of available zoom levels inside the cubic image.
  • Min_zoom_level_size: Number of tiles per cubic face on the minimum zoom level.
  • Source_name: Name of the source file name. Normally, this is the name of the panorama (equirectangular) image.
  • Shot_date: Date of the image capture. Format: YYYY-MM-DD hh:mm:ss
  • Srid: EPSG code of the projection system used for the EO parameters calculation.
  • Camera_height: Relative elevation between the camera system and the ground in meters.

https://your.mapspace.com/mapSvcs/INWFSProxyStreetSSL?service=WFS&version=1.1.0&request=GetFeature&srsname=EPSG:4326&typename=street_line&userkey=XXXXXX&bbox=10.611092055463237,59.90716892739954,10.674520934247417,59.92369053200554

SEStreetBbox

This service will locate all the Street photos whose centers are located inside of a given extent.

SEStreetBbox Parameters

The parameters needed in the request URL are the following:

  • bbox [mandatory]: Bounding Box defined by four coordinates that specify the area in the specified projection system. Coordinates are provided in the following order: minimum X coordinate, minimum Y coordinate, maximum X coordinate, maximum Y coordinate.

  • crs [mandatory]: Projection system used, It must follow OGC nomenclature. For example EPSG:32630 for WGS84 UTM 30 North or EPSG:3785 for Spherical Mercator projection.

  • output [mandatory]: Response format. Possible values are:

    • txt: Response is a text string with comma-separated values (“,”).
    • Xml: Response is an XML file.
    • Json: Response is Json format.

  • date [optional] : A date following the structure YYYYMMDD or YYYYMM or YYYY. The service will use the most current images available, whose date is previous to the requested date. It is also possible to use a range of dates with the structure YYYYMMDD-YYYYMMDD, in this case the images used will be the most current ones available in the specified date range.If the parameter is omitted the system will submit the most recent version of the tile.

  • metadata [optional]: This parameter allows to obtain all metadata info for all images inside the searching area.

  • userkey [mandatory]: User’s key for authentication purposes. This key is unique for each client and must be requested to Field Group.

Error messages

If no images are found for the specified point an Error message is returned. If the response format was specified as a text, the response message is:

ERROR, Error message text

If the response format is XML the error XML file is:

<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?> 
<result> 
	<Error> 
		ERROR, Error message text 
	</Error> 
</result>

Usage

The https request for searching the available images on a bounding box would be like this:

https://your.mapspace.com/mapSvcs/SEStreetBbox?crs=EPSG:4326&bbox=10.218658438246603,60.153809133223405,10.220031729266088,60.15449257649393&userkey=XXXXXX&output=xml

For each Street image located the following information is provided:

  • Id (Street image identifier)
  • Xcp: longitude location of the image centroid (EPSG:4326)
  • Ycp: latitude location of the image centroid (EPSG:4326)
  • Zcp: Altitude to the sea level of the image centroid in meters
  • Srid: Local projection system (EPSG code) for the EO calculation
  • Camera_height: Camera system elevation to the ground.
  • Xcp_local: X location in local projection system (Srid)
  • Ycp_local: Y location in local projection system (Srid)

SEStreet

This service will locate all the Street photos whose centers are located inside of a given extent defined with a ratio from a location defined by a coordinate or a Street Image identifier

SEStreet Parameters

Parameters of the service are described below:

  • id [optional]: ID of the Street image.
  • x [optional]: Coordinate x or longitude in the specified projection system.
  • y [optional]: Coordinate y or latitude in the specified projection system. The x,y location or id value must be used.
  • ratio [mandatory]: searching ratio in meters.
  • crs [mandatory]: Projection system used, It must follow OGC nomenclature. For example EPSG:32630 for WGS84 UTM 30 North or EPSG:3857 for Spherical Mercator projection.
  • output [mandatory]: Response format. Possible values are:
    • txt: Response is a text string with comma-separated values (“,”).
    • Xml: Response is an XML file.
    • Json: Response is Json format.
  • date [optional] : A date following the structure YYYYMMDD or YYYYMM or YYYY. The service will use the most current images available, whose date is previous to the requested date. It is also possible to use a range of dates with the structure YYYYMMDD-YYYYMMDD, in this case the images used will be the most current ones available in the specified date range.If the parameter is omitted the system will submit the most recent version of the tile.
  • Layer [optional]: This parameter restricts the search to the selected Street layer.
  • userkey [mandatory]: User’s key for authentication purposes. This key is unique for each client and must be requested to Field Group.

Error messages

If no images are found for the specified point an Error message is returned. If the response format was specified as a text, the response message is:

ERROR, Error message text

If the response format is XML the error XML file is:

<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?> 
<result> 
	<Error> 
		ERROR, Error message text 
	</Error> 
</result>

Usage

Following is an example of a request for searching all panorama images in a given point with a distance radius:

https://your.mapspace.com/mapSvcs/SEStreet?crs=EPSG:4326&x=18.07963810&y=59.28996795&ratio=50&userkey=XXXXXX&output=xml

The image selected by the identifier or the nearest image to the x,y location will be provided with all metadata. The other images will be provided with a limited number of parameters: Main image:

  • Id (Street image identifier).
  • IdSet: Set of images identifier.
  • Imagename: source image name.
  • Shotdate: Image capture date.
  • Xcp: longitude location of the image centroid (EPSG:4326).
  • Ycp: latitude location of the image centroid (EPSG:4326).
  • Zcp: Altitude to the sea level of the image centroid in meters.
  • Direction_yaw: Car direction to the North in degrees.
  • Min_zoom_level_size: Number of tiles of the minimum zoom levels per cubic face.
  • Zoom_levels: Number of zoom levels per cubic face.
  • Tile_size: pixel tile size (x & y axis).
  • Id_dtm: Available Dtm for the street image.
  • Id_dsm: Available Dsm for the street image.
  • Omega: EO angle of the main frame.
  • Phi: EO angle of the main frame.
  • Kappa: EO angle of the main frame.
  • Ext0,1,2,3,4,5,6,7,8: Rotation matrix parameters.
  • Xcp_local: X location in local projection system (Srid).
  • Ycp_local: Y location in local projection system (Srid).
  • Zcp_local: Altitude to the sea level of the image centroid in meters.
  • Equi_img_width: Source equirectangular image with (pixels).
  • Column_center: column pixel center of source equirectangular image.
  • Row_center: Row pixel center of source equirectangular image.
  • Pixel_angle: Number of pixels per degree.
  • Srid: Local projection system (EPSG code) for the EO calculation.
  • Camera_height: Camera system elevation to the ground.
  • Street_type: Street layer name.
  • Depthmapavailable: Depthmap file availability for measurements.
  • Copyright: image copyright.

Images on the searching area:

  • Id (Street image identifier).
  • Xcp: longitude location of the image centroid (EPSG:4326).
  • Ycp: latitude location of the image centroid (EPSG:4326).
  • Zcp: Altitude to the sea level of the image centroid in meters.
  • Srid: Local projection system (EPSG code) for the EO calculation.
  • Camera_height: Camera system elevation to the ground.
  • Xcp_local: X location in local projection system (Srid).
  • Ycp_local: Y location in local projection system (Srid).

SENearestStreet

This service will obtain all metadata information of the nearest Street image to the location provided.

SENearestStreet Parameters

Parameters of the service are described below:

  • x [mandatory]: Coordinate x or longitude in the specified projection system.
  • y [mandatory]: Coordinate y or latitude in the specified projection system.
  • ratio [mandatory]: searching ratio in meters.
  • crs [mandatory]: Projection system used, It must follow OGC nomenclature. For example EPSG:32630 for WGS84 UTM 30 North or EPSG:3857 for Spherical Mercator projection.
  • output [mandatory]: Response format. Possible values are:
    • txt: Response is a text string with comma-separated values (“,”).
    • Xml: Response is an XML file.
    • Json: Response is Json format.
  • date [optional] : A date following the structure YYYYMMDD or YYYYMM or YYYY. The service will use the most current images available, whose date is previous to the requested date. It is also possible to use a range of dates with the structure YYYYMMDD-YYYYMMDD, in this case the images used will be the most current ones available in the specified date range. If the parameter is omitted the system will submit the most recent version of the tile.
  • Layer [optional]: This parameter restricts the search to the selected Street layer.
  • userkey [mandatory]: User’s key for authentication purposes. This key is unique for each client and must be requested to Field Group.

Error messages

If no images are found for the specified point an Error message is returned. If the response format was specified as a text, the response message is:

ERROR, Error message text

If the response format is XML the error XML file is:

<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?> 
<result> 
	<Error> 
		ERROR, Error message text 
	</Error> 
</result>

Usage

Following is an example of a request for obtaining all images in a given point and a distance radius:

https://your.mapspace.com/mapSvcs/SENearestStreet?crs=EPSG:4326&x=18.07963810&y=59.28996795&ratio=50&userkey=XXXXXX&output=xml

For each Street image located the following information is provided:

  • Id (Street image identifier).
  • IdSet: Set of images identifier.
  • Imagename: source image name.
  • Shotdate: Image capture date.
  • Xcp: longitude location of the image centroid (EPSG:4326).
  • Ycp: latitude location of the image centroid (EPSG:4326).
  • Zcp: Altitude to the sea level of the image centroid in meters.
  • Direction_yaw: Car direction to the North in degrees.
  • Min_zoom_level_size: Number of tiles of the minimum zoom levels per cubic face.
  • Zoom_levels: Number of zoom levels per cubic face.
  • Tile_size: pixel tile size (x & y axis).
  • Id_dtm: Available Dtm for the street image.
  • Id_dsm: Available Dsm for the street image.
  • Omega: EO angle of the main frame.
  • Phi: EO angle of the main frame.
  • Kappa: EO angle of the main frame.
  • Ext0,1,2,3,4,5,6,7,8: Rotation matrix parameters.
  • Xcp_local: X location in local projection system (Srid).
  • Ycp_local: Y location in local projection system (Srid).
  • Zcp_local: Altitude to the sea level of the image centroid in meters.
  • Equi_img_width: Source equirectangular image with (pixels).
  • Column_center: column pixel center of source equirectangular image.
  • Row_center: Row pixel center of source equirectangular image.
  • Pixel_angle: Number of pixels per degree.
  • Srid: Local projection system (EPSG code) for the EO calculation.
  • Camera_height: Camera system elevation to the ground.

DAGetStreetTile

This service returns a tile of a Street image specified in the request by the image ID and the tile ID.

The desired tile to cover a given point at a desired Zoom Level in a cubic face can be calculated from the data provided in the INWFSProxyStreet or SEStreetBbox services as follows:

X = PositionX / ( 256 * 2 (Zoom_level))
Y = PositionY / ( 256 * 2 (Zoom_level))

DAGetStreetTile Parameters

Parameters of the service are described below:

  • id [mandatory]: This is the identifier of the street image the tile belongs to.
  • meshid [mandatory]: Tile coding inside the Mapspace structure, as follows:
    • F_T_Y_X, where:
      • F Cubic face: f, b, r, l, u, d
      • T zoom level: 0,1,2,3…
      • Y Row occupied by the tile in the provided zoom level
      • X Column occupied by the tile in the provided zoom level
  • userkey [mandatory]: User’s key for authentication purposes. This key is unique for each client and must be requested to Field Group.

Usage

Example of an tile image request with Street image Id provided:

https://your.mapspace.com/mapSvcs/DAGetStreetTile?userkey=XXXXXXid=C+018.080492_59.282739_160807&meshid=f_2_1_2

The result of the request will be a JPG image. If the user is not authorized to get the requested data or if the requested tile is not available, a transparent PNG file 256 x 256 pixels will be returned.

MDGetStreet

The service returns all available metadata of a given street image.

The result of the service will be all the information for the Street image that is stored in the Mapspace database.

MDGetStreet Parameters

Parameters of the service are described below:

  • id [mandatory]: This is the identifier of the street image the tile belongs to.
  • output [mandatory]: Response format. Possible values are:
    • txt: Response is a text string with comma-separated values (“,”).
    • Xml: Response is an XML file.
    • Json: Response is Json format.
  • userkey [mandatory]: User’s key for authentication purposes. This key is unique for each client and must be requested to Field Group.

Usage

Example of a street image metadata request:

https://your.mapspace.com/mapSvcs/MDGetStreet?userkey=XXXXXX&id=C+010.260788_60.082537_160708&output=json

For each Street image located the following information is provided:

  • Id (Street image identifier).
  • IdSet: Set of images identifier.
  • Imagename: source image name.
  • Shotdate: Image capture date.
  • Xcp: longitude location of the image centroid (EPSG:4326).
  • Ycp: latitude location of the image centroid (EPSG:4326).
  • Zcp: Altitude to the sea level of the image centroid in meters.
  • Direction_yaw: Car direction to the North in degrees.
  • Min_zoom_level_size: Number of tiles of the minimum zoom levels per cubic face.
  • Zoom_levels: Number of zoom levels per cubic face
  • Tile_size: pixel tile size (x & y axis).
  • Id_dtm: Available Dtm for the street image.
  • Id_dsm: Available Dsm for the street image.
  • Omega: EO angle of the main frame.
  • Phi: EO angle of the main frame.
  • Kappa: EO angle of the main frame.
  • Ext0,1,2,3,4,5,6,7,8: Rotation matrix parameters.
  • Xcp_local: X location in local projection system (Srid).
  • Ycp_local: Y location in local projection system (Srid).
  • Zcp_local: Altitude to the sea level of the image centroid in meters.
  • Equi_img_width: Source equirectangular image with (pixels).
  • Column_center: column pixel center of source equirectangular image.
  • Row_center: Row pixel center of source equirectangular image.
  • Pixel_angle: Number of pixels per degree.
  • Srid: Local projection system (EPSG code) for the EO calculation.
  • Camera_height: Camera system elevation to the ground.

TRPointsStreet

This service will be used to transform world coordinates to pixel coordinates in a given Street image, and vice versa. This service needs the ID of a Street image, against which all conversions are carried out.

TRPointsStreet Parameters

The parameters for this service are:

  • coors [mandatory]: This parameter is a list of coordinates separated by commas. The following rules must be observed to provide the list:
    • The number of coordinates must be an even number in 2D input values.
    • Odd coordinates, represent X coordinates in 2D input values.
    • Even coordinates, represent Y coordinates in 2D input values.
    • in 3D input values, the order is x,y,z
  • Crs [mandatory]: Projection system of the world coordinates used or requested. It must follow OGC nomenclature. For example EPSG:32630 for WGS84 UTM 30 North or EPSG:3857 for Spherical Mercator projection.
  • output [mandatory]: Response format. Possible values are:
    • txt: The result of the service will be the list of transformed coordinates.
    • Xml: The result is an XML file, with the list of transformed coordinates.
    • Json: The result is an json file, with the list of transformed coordinates.
  • id [mandatory]: This is the ID of the Oblique image used.

• type [mandatory]: This parameter defines how the conversion is done according to the following values:

  • mode [mandatory]: This parameter defines how the conversion is done according to the following values:
    • wts2d, The service will convert world 2D coordinates to point coordinates of the street image at ground level.
    • wts3d, The service will convert world 3D coordinates to point coordinates of the Street image.
    • stw, The service will convert point coordinates of the Street image at a identified distance to world coordinates.
    • stwdm, The service will convert point coordinates of the Street image at a identified distance to world coordinates using a Depth map image of the street image. This is the most accurate option. The point Street values are defined by two values in a spherical coordinate system: Theta & Phi

The Theta value is the azimuthal angle (longitude) measured from the x-axis in the xy plane by the pixel angle factor:

Theta (px) = Theta (rad) * pixel_angle

The Phi value is the polar angle or zenith angle or colatitudes and measured from the positive z-axis by the pixel angle.

Phi (px) = Phi (rad) * pixel_angle

The pixel coordinates are result of the equirectangular projection system:

  • userkey [mandatory]: User’s Key for authentication purposes. This key is unique for each client and must be requested to Field Group.

Usage

  1. Transformation of pixel coordinates & distance to world coordinates with Xml output

The request to the service would be made as follows:

https://your.mapspace.com/mapSvcs/TRPointsStreet?userkey=*****************&coors=1393,1654,22.7,1393,1654,20.7&id=C+018.079480_59.289828_160822&mode=stw&crs=EPSG:3011&output=xml

The result of the service is a XML file with two couples of coordinates:

<result>
<Point>
<X>154513.22949788778</X>
<Y>6574972.091435375</Y>
    <Z>50.19940081274179</Z>
</Point>
<Point>
<X>154514.6772954306</X>
<Y>6574970.8465512</Y>
<Z>49.60429941955603</Z>
</Point>
</result>
  1. Transformation of 2D world to pixel coordinates with plain text output

The request to the service would be made as follows:

https://your.mapspace.com/mapSvcs/TRPointsStreet?userkey=XXXXXX&coors=18.07963810,59.28996795,18.07973810,59.28986795&id=C+018.079480_59.289828_160822&mode=wts2d&crs=EPSG:3011&output=xml

The result is a text string containing as many coordinates as values in the points parameter (in this example, there are only two). The response for this request should be:

3166.2221705364805,2226.9722500327634,4123.528453949508,2237.770322191771,
  1. Transformation of 3D world to pixel coordinates with plain text output

The request to the service would be made as follows:

https://your.mapspace.com/mapSvcs/TRPointsStreet?userkey=XXXXXX &coors=18.07963810,59.28996795,50.5&id=C+018.079480_59.289828_160822&mode=wts3d&crs=EPSG:3011&output=txt

The result is a text string containing as many coordinates as values in the points parameter (in this example, there are only two). The response for this request should be:

3143.6613428076703,1524.2795542874042