Mapspace API Reference

Class: Image

Mapspace.oblique. Image

The object that represents a single oblique image from Terratec. The object has an object with the metadata and do transformations for coordinates.

new Image(options)

Parameters:
Name Type Description
options Mapspace.oblique.ImageOptions

Oblique image options. Take care that this options are not optional and must be present.
Source:
mapspace-oblique/obliqueimage.js
Fires:
  • ol.events.Event#event:gridloaded

Extends

  • ol.Object

Methods

computeShotDate()

Computes the shot date in the format YYYY-MM-dd.

Source:
mapspace-oblique/obliqueimage.js

fromLocalCoordToPixelCoord(coordinates)

Transforms coordinates from a local spherical mercator XY coordinate to pixel XY coordinates inside an oblique image. The oblique viewer uses internally a fake spherical mercator projection in which oblique images are rendered as if they where full earth images. This function translates that fake coordinates to pixel coordinates. Pixel coordinates have origin at left top corner. X increases to the right and Y increases to the bottom. Both always positive values. Local coordinates are as spherical mercator. Origin is at the center of the image and axis are cartesian.

Parameters:
Name Type Description
coordinates Mapspace.Coordinate | ?Array.<Mapspace.Coordinate>

Coordinates as XY in Spherical Mercator.
Source:
mapspace-oblique/obliqueimage.js
Returns:

Coordinates transformed as x, y in pixels.

Type
Mapspace.Coordinate | ?Array.<Mapspace.Coordinate>

fromLocalResolution(localResolution)

Converts from local fake resolution to real one.

Parameters:
Name Type Description
localResolution number

The local resolution in meters per pixel.
Source:
mapspace-oblique/obliqueimage.js
Returns:

The real resolution or null if resolutions are not defined or if fake resolution is outside resolution ranges.

Type
number

fromObliqueProjCoordToPixelCoord(coordinate)

Trasforms world coordinate in oblique projection to XY pixel coordinates using a TEG source for elevation data. If a TEG source is not set then a mean elevation is used for an aproximated calculation.

Parameters:
Name Type Description
coordinate Mapspace.Coordinate

Coordinates as XY in oblique projection. Each oblique has defined a projection that can be obtained in the epsg property of the metadata.
Source:
mapspace-oblique/obliqueimage.js
Returns:

Coordinates a XY oblique image pixels or null.

Type
Mapspace.Coordinate

fromPixelCoordToLocalCoord(coordinates)

Transforms coordinates from pixel XY coordinate inside an oblique image to a local spherical mercator XY coordinates. The oblique viewer uses internally a fake spherical mercator projection in which oblique images are rendered as if they where full earth images. This function translates pixel coordinates to that fake coordinates. Pixel coordinates have origin at left top corner. X increases to the right and Y increases to the bottom. Both always positive values. Local coordinates are as spherical mercator. Origin is at the center of the image and axis are cartesian.

Parameters:
Name Type Description
coordinates Mapspace.Coordinate | ?Array.<Mapspace.Coordinate>

Coordinates as XY in image pixels.
Source:
mapspace-oblique/obliqueimage.js
Returns:

Coordinates transformed as x, y in Spherical Mercator.

Type
Mapspace.Coordinate | ?Array.<Mapspace.Coordinate>

fromPixelCoordToObliqueProjCoord(coordinate, elevation)

Transforms for XY pixel coordinate to world coordinate in oblique projection using a TEG source for elevation data. If a TEG source is not set then a mean elevation is used for an aproximated calculation.

Parameters:
Name Type Description
coordinate Mapspace.Coordinate

Coordinate as XY pixel.
elevation number

Aproximated ground elevation.
Source:
mapspace-oblique/obliqueimage.js
Returns:

Coordinates as XY in oblique projection. Each oblique has defined a projection that can be obtained in the epsg property of the metadata.

Type
Mapspace.Coordinate

fromPixelCoordToWorldCoord(coordinates, noPromise)

Transform XY pixel coordinates to world coordinates in lon-lat 'EPSG:4326' projection. Pixel coordinates XY are the coordinates used internally in oblique imagery. Pixel coordinates have origin at left top corner. X increases to the right and Y increases to the bottom. Both always positive values.

Parameters:
Name Type Description
coordinates Mapspace.Coordinate | ?Array.<Mapspace.Coordinate>

Coordinates in pixels.
noPromise boolean

Indicates if service must return a promise.
Source:
mapspace-oblique/obliqueimage.js
Returns:

The transformed coordinates as longitude and latitude or a Promise that returns transformed coordinates. Returns null if no coordinates are passed.

Type
Mapspace.Coordinate | ?Array.<Mapspace.Coordinate> | Promise

fromPixelCoordToWorldCoordUsingGrid(coordinates)

Transform XY pixel coordinates to world coordinates in lon-lat 'EPSG:4326' projection using an inverse transformation grid through a bilinear interpolation.

If the oblique image has a TEG source associated then grid transformation is ignored and this function calls fromPixelCoordToWorldCoord.

Input coordinates must be enforced to be inside the extent.

Parameters:
Name Type Description
coordinates Mapspace.Coordinate | ?Array.<Mapspace.Coordinate>

Coordinates as XY pixel coordinates.
Source:
mapspace-oblique/obliqueimage.js
Returns:

The transformed coordinates in longitude and latitude.

Type
Mapspace.Coordinate | ?Array.<Mapspace.Coordinate>

fromRealResolution(realResolution)

Converts from real resolution to local fake one.

Parameters:
Name Type Description
realResolution number

The real resolution in meters per pixel.
Source:
mapspace-oblique/obliqueimage.js
Returns:

The local fake resolution or null if resolutions are not defined or if real resolution is outside resolution ranges.

Type
number

fromRealZoomLevel(zoom)

Converts from real zoom level to local fake resolution.

Parameters:
Name Type Description
zoom number

The real zoom level. Notice that numbers do not need to be integers.
Source:
mapspace-oblique/obliqueimage.js
Returns:

The local fake resolution.

Type
number

fromWorldCoordToPixelCoord(coordinates, noPromise)

Transform world coordinates in lon-lat 'EPSG:4326' projection to XY pixel coordinates. Pixel coordinates XY are the coordinates used internally in oblique imagery. Pixel coordinates have origin at left top corner. X increases to the right and Y increases to the bottom. Both always positive values.

Parameters:
Name Type Description
coordinates Mapspace.Coordinate | ?Array.<Mapspace.Coordinates>

Coordinates as longitude and latitude.
noPromise boolean

Indicates if service must return a promise.
Source:
mapspace-oblique/obliqueimage.js
Returns:

The transformed coordinates in pixels or a Promise that returns XY transformed coordinates. Returns null if no coordinates are passed.

Type
Mapspace.Coordinate | ?Array.<Mapspace.Coordinate> | Promise

fromWorldCoordToPixelCoordUsingGrid(coordinates)

Transform world coordinates in lon-lat 'EPSG:4326' projection to XY pixel coordinates using a transformation grid through a bilinear interpolation.

If the oblique image has a TEG source associated then grid transformation is ignored and this function calls fromWorldCoordToPixelCoord.

Input coordinates must be enforced to be inside the extent.

Parameters:
Name Type Description
coordinates Mapspace.Coordinate | ?Array.<Mapspace.Coordinate>

Coordinates as longitude and latitude.
Source:
mapspace-oblique/obliqueimage.js
Returns:

The transformed coordinates in pixels.

Type
Mapspace.Coordinate | ?Array.<Mapspace.Coordinate>

getBestResolution(resolution)

Returns the best resolution for a given resolution value. The resolution is ensured to be inside the resolutions of this image. The returned result is a pair of values, the first is the real resolution in meters per pixel. The second is the fake resolution for the internal oblique viewer.

Parameters:
Name Type Description
resolution number

The resolution in meters per pixel.
Source:
mapspace-oblique/obliqueimage.js
Returns:

[realRes, fakeRes].

Type
Array.<number>

getBoundaryCoordinates()

Returns the array of five coordinates that define the boundary of the image. The first and last coordinates are the same to have a closed ring. The ring follows the counter-clockwise order starting at the most north-west one. Coordinates are always in WGS84 latlon, first value in the coordinate is longitude and second latitude. Returns null if the metadata is not set.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
Array.<Mapspace.Coordinate>

getCopyright()

Returns image copyright.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
string

getExtent()

Returns the extent of the oblique image in 'EPSG:4326' lonlat.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
Mapspace.Extent

getExtraZoomLevels()

Returns the number of extra zoom levels of the oblique image or zoom levels to add to default zoom levels. In the new zoom levels the tiles will be rescaled.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
number

getGrid()

Returns the direct grid to do interpolations as it is returned in the resolve function by Mapspace.promises.oblique#getTransformationGrid.

The direct grid is returned as an array (rows) with arrays of Mapspace.Coordinate inside (columns). Coordinates are always in pixels so this grid is useful when overlapping vectors on top of an oblique image that come in world coordinates.

The oblique image extent is sliced in columns and rows and the grid returned has rows + 1 x columns + 1 coordinates, the first one at the bottom left coordinate of the image extent and the last one at the top right. These coordinates are then transformed to pixels in the oblique image.

To load a direct grid first check if isLoadingGrid is false, then create a listener for the GRIDLOADED event, then call loadGrid, and then check in the listener if getGridError was null or not.

var grid = image.getGrid();
var gridLoaded = function() {
    var err = image.getGridError();
    if (err) return;
    // Code here to execute once the direct grid is loaded
};
if (grid) {
    gridLoaded();
} else {
    if (!image.isLoadingGrid()) {
        image.once(Mapspace.oblique.ImageEventType.GRIDLOADED, gridLoaded, this);
        image.loadGrid();
    }
}
Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
Array.<Array.<Mapspace.Coordinate>> | null

getGridError()

Returns the error requesting direct grid to do interpolations as it is returned in the reject function by Mapspace.promises.oblique#getTransformationGrid. To load a direct grid first check if isLoadingGrid is false, then create a listener for the GRIDLOADED event, then call loadGrid, and then check in the listener if getGridError was null or not.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
Error | null

getHeight()

Returns the height in pixels of this image.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
number

getInverseGrid()

Returns the inverse grid to do interpolations as it is returned in the resolve function by Mapspace.promises.oblique#getTransformationInverseGrid.

The inverse grid is returned as an array (rows) with arrays of Mapspace.Coordinate inside (columns). Coordinates are always in lonlat WGS84 world coordinates so this grid is useful when clicking or interacting inside an oblique image to transform to world coordinates.

The oblique image extent is sliced in columns and rows and the grid returned has rows + 1 x columns + 1 coordinates, the first one at the bottom left coordinate of the image extent and the last one at the top right. These coordinates are then transformed to world coordinates in the oblique image.

To load a inverse grid first check if isLoadingInverseGrid is false, then create a listener for the INVERSEGRIDLOADED event, then call loadInverseGrid, and then check in the listener if getInverseGridError was null or not.

var grid = image.getInverseGrid();
var gridLoaded = function() {
    var err = image.getInverseGridError();
    if (err) return;
    // Code here to execute once the inverse grid is loaded
};
if (grid) {
    gridLoaded();
} else {
    if (!image.isLoadingInverseGrid()) {
        image.once(Mapspace.oblique.ImageEventType.INVERSEGRIDLOADED, gridLoaded, this);
        image.loadInverseGrid();
    }
}
Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
Array.<Array.<Mapspace.Coordinate>> | null

getInverseGridError()

Returns the error requesting inverse grid to do interpolations as it is returned in the reject function by Mapspace.promises.oblique#getTransformationInverseGrid. To load a inverse grid first check if isLoadingInverseGrid is false, then create a listener for the INVERSEGRIDLOADED event, then call loadInverseGrid, and then check in the listener if getInverseGridError was null or not.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
Error | null

getMetadata()

Returns the metadata of the oblique image.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
Mapspace.ObliqueMetadata

getObliqueResolutions()

Returns an array with pair of resolutions in meters per pixel for each zoom level inside the oblique in descending value order. The first resolution in each pair is the real mean resolution for the oblique. The second resolution in each pair is the fake resolution that the ol.Map object uses to draw the oblique.

Source:
mapspace-oblique/obliqueimage.js
Returns:

An array of pairs of numbers. [[realRes0, fakeRes0], ..., [realResN, fakeResN]]

Type
Array.<Array.<number>>

getResolutionForMosaic()

Returns the real resolution at which is most suitable to switch between natural oblique image and seamless oblique mosaic image.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
number

getResolutions()

Returns the resolutions of the oblique image, an array with pair of resolutions in meters per pixel for each zoom level inside the oblique in descending value order. The first resolution in each pair is the real mean resolution for the oblique. The second resolution in each pair is the fake resolution that the ol.Map object uses to draw the oblique. [[realRes0, fakeRes0], ..., [realResN, fakeResN]]

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
Array.<Array.<number>>

getShotDate()

Returns the shot date in the format YYYY-MM-dd.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
string

getTegID()

Returns the ID of the TEG source that this image must use, or null if no TEG if set for the image.

Source:
mapspace-oblique/obliqueimage.js
Returns:

TEG source ID.

Type
string

getTegList(level)

Returns an array of Tile ID in the quadtree for tiles that are inside the oblique extent.

Parameters:
Name Type Description
level number

Quadtree zoom level.
Source:
mapspace-oblique/obliqueimage.js
Returns:

Array of tile IDs.

Type
Array.<string>

getTegTileCoords(level)

Returns an array of tile coords for tiles that are inside the oblique extent.

Parameters:
Name Type Description
level number

Quadtree zoom level.
Source:
mapspace-oblique/obliqueimage.js
Returns:

Array of tile coords.

Type
Array.<ol.TileCoord>

getWidth()

Returns the width in pixels of this image.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
number

getZoomLevel(localRes)

Returns the zoom level of a given fake resolution.

Parameters:
Name Type Description
localRes number

The local resolution in meters per pixel.
Source:
mapspace-oblique/obliqueimage.js
Returns:

The zoom level or null if wasn't found.

Type
number

isGeometryInsideOblique(geom)

Returns true if the geometry or extent is inside the oblique image limits. Coordinates must be in Mercator Spheric. The oblique limits are a trapezoid geometry of irregular sides. Due to small extension of oblique imagery the limits are considered as a plane instead of a geodesic surface.

Parameters:
Name Type Description
geom ol.geom.Geometry | Mapspace.Extent

A geometry or a extent.
Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
boolean

isLoadingGrid()

Returns if the image is loading a direct grid or not.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
boolean

isLoadingInverseGrid()

Returns if the image is loading a inverse grid or not.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
boolean

isPixelInside(pixel, useBorderRatio)

Returns true if the pixel coordinates are inside the valid portion of the oblique image. We are in the valid portion when we are inside a buffer of a percentage of the border defined in Mapspace.OBLIQUE_BORDER_RATIO constant.

Parameters:
Name Type Description
pixel Mapspace.Coordinate

Pixel coordinates XY. Coordinates here can be negative values. If that happens then the function returns false. X values inside a oblique are always positive, X increasing rightward and Y downward from origin that is at top-left corner.
useBorderRatio boolean

If remove a border from image using the value Mapspace.OBLIQUE_BORDER_RATIO;
Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
boolean

isPointInsideExtent(point)

Returns true if the point coordinates are inside the extent of the oblique image. The extent is the minimum rectangle bounding the oblique image. This function do not ensure the point is inside the oblique.

Parameters:
Name Type Description
point Mapspace.Coordinate

World lonlat coordinates.
Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
boolean

isTegCached()

Returns if all the Teg tiles needed for calculations are currently cached and available or not.

Source:
mapspace-oblique/obliqueimage.js
Returns:
Type
boolean

loadGrid()

Requests a direct transformation grid for this image and loads it. When the new grid is lodaded the image notifies it with a GRIDLOADED event. See Mapspace.oblique.Image#getGrid about how to use this function.

Source:
mapspace-oblique/obliqueimage.js

loadGrids()

Returns a promise that loads both the direct and inverse grid for this image.

Source:
mapspace-oblique/obliqueimage.js
Returns:

A Promise that returns this image for the resolve function and null for the reject function. Any error happened is stored in gridError.

Type
Promise

loadInverseGrid()

Requests an inverse transformation grid for this image and loads it. When the new grid is lodaded the image notifies it with an INVERSEGRIDLOADED event. See Mapspace.oblique.Image#getInverseGrid about how to use this function.

Source:
mapspace-oblique/obliqueimage.js

loadTegTiles()

Returns a promise that returns all the tiles for this oblique image, either from cache or from requests. Promise rejects if any of the tiles fails to be returned.

Source:
mapspace-oblique/obliqueimage.js
Returns:

A Promise that returns an array of Mapspace.TegTile for the resolve function or an error for the reject function.

Type
Promise

requestTransformationFunction()

Returns a promise that requests the transformation function that transforms between WGS84 Lat/Lon coordinates and the local projection of the image and the inverse.

Source:
mapspace-oblique/obliqueimage.js
Returns:

A promise that returns this image for the resolve function and null for the reject function. Any error happened is stored in transformError and inverseTransformError.

Type
Promise

toRealZoomLevel(localResolution)

Converts from local fake resolution to real zoom level.

Parameters:
Name Type Description
localResolution number

The local resolution in meters per pixel.
Source:
mapspace-oblique/obliqueimage.js
Returns:

The real zoom level or null if resolutions are not defined or if local fake resolution is outside resolution ranges. Notice that result numbers do not need to be integers.

Type
number

updateFeature(feature)

Updates a ol.Feature creating a new ol.geom.Geometry object with the geometry transformed from world coordinates in 'EPSG:3857' Spherical Mercator to local fake image XY coordinates. The oblique viewer uses internally a fake spherical mercator projection in which oblique images are rendered as if they where full earth images. This function translates world coordinates to that fake coordinates.

The new geometry object is stored in the observable property called Mapspace.OBLIQUE_GEOMETRY_NAME.

For the transformation it is only used the grid of the image, so if there is not a grid present, this function does nothing.

The transformation only take care of X and Y coords (first two values of each coordinate). The third value and above will remain unchanged so this function works with any stride.

Parameters:
Name Type Description
feature ol.Feature

Input feature. World coordinate 'EPSG:3857' geometry is stored in the observable property Mapspace.GEOMETRY_NAME. New local coordinate geometry created is stored in observable property called Mapspace.OBLIQUE_GEOMETRY_NAME.
Source:
mapspace-oblique/obliqueimage.js

updateFeatureFromLocal(feature)

Returns a Promise that updates a feature from local coordinates to world coordinates.

Initially the geometry object with local coordinates must be stored in the observable property called Mapspace.GEOMETRY_NAME.

Then that geometry object with local coordinates will be converted to world coordinates and stored in the observable property called Mapspace.GEOMETRY_NAME and the geometry object with local coordinates will be moved to the observable property called Mapspace.OBLIQUE_GEOMETRY_NAME.

Parameters:
Name Type Description
feature ol.Feature

The feature.
Source:
mapspace-oblique/obliqueimage.js
Returns:

A Promise that returns true for the resolve function or Error for the reject function.

Type
Promise