nokia.maps.geo.BoundingBox

Class Summary

This class represents a rectangular area specified by two geographic coordinates.

[ For full details, see nokia.maps.geo.BoundingBox ]

Table 1. Property Summary
Properties

readonly  bottomRight: {nokia.maps.geo.Coordinate}

This property holds an object containing geographic coordinates of the bottom right of the bounding box.

readonly  isCDB: {Boolean}

This property holds a flag indicating whether the bounding box crosses the date border (true>) or not (false).

readonly  topLeft: {nokia.maps.geo.Coordinate}

This property holds an object containing geographic coordinates of the top left of the bounding box.

Table 2. Method Summary
Methods

contains (bbox) : {Boolean}

This method checks if the object supplied by the caller lies within the area of the given bounding box.

static  coverAll (coordinates) : {nokia.maps.geo.BoundingBox}

This constructs a bounding box from an array of point objects (instances of Coordinate).

static  fromObject (obj, skipValidation) : {nokia.maps.geo.BoundingBox}

This method constructs an instance of BoundingBox from a set of parameters supplied by the caller.

static  fromPath (path, skipValidation) : {nokia.maps.geo.BoundingBox}

This method constructs a bounding box from a Strip object that represents a path.

getCenter () : {nokia.maps.geo.Coordinate}

This method returns an object containing the coordinates of the center of the given bounding box.

getHeight () : {Number}

This method returns the height of the bounding box in decimal degrees.

getWidth () : {Number}

This method returns the width of the bounding box in decimal degrees.

intersects (bbox)

This method checks if the intersection of two bounding boxes is non-empty.

isEmpty ()

The method checks if the area enclosed by the given bounding box is 0.

static  merge (boxes) : {nokia.maps.geo.BoundingBox}

This method returns the smallest bounding box that covers all given boxes.

merge (boxes)

This method returns the smallest bounding box that covers the given bounding box and those supplied by the caller.

resizeToCenter (center) : {nokia.maps.geo.BoundingBox}

This method clones the given bounding box and resizes the clone if necessary until the location supplied by the caller is at its center.

Class Description

This class represents a rectangular area defined in terms of the geographic coordinates its top-left and bottom-right corners. A bounding box is not necessarily the smallest rectangle spanned by the two points. A bounding box wider than 180° or higher than 90° can be defined by setting the longitude of the top-left corner to a larger value than the longitude of the bottom-right corner. An instance of BoundingBox is immutable.

Constructor Details

nokia.maps.geo.BoundingBox(topLeft, bottomRight, skipValidation)

This method initializes a new instance of BoundingBox.

Parameters:
 
topLeft:
{nokia.maps.geo.Coordinate}
 
An object containing the geographical coordinates of the top left corner; latitude must be greater or at least the same as the latitude of bottomRight; longitude should be smaller than the longitude of bottomRight
bottomRight:
{nokia.maps.geo.Coordinate} [optional]
 
An object containing the geographical coordinates of the bottom right corner; latitude must be lower or at least the same as the latitude of the top left corner; longitude should be greater than the longitude of the top left corner
skipValidation:
{Boolean} [optional]
 
A flag indicating if the validation of the latitude is to be omitted; true means that no validation occurs, in which case the caller must ensure that the latitude of the bottom right corner is greater than that of the top left

Property Details

readonly  bottomRight: {nokia.maps.geo.Coordinate}

This property holds an object containing geographic coordinates of the bottom right of the bounding box.

 

readonly  isCDB: {Boolean}

This property holds a flag indicating whether the bounding box crosses the date border (true>) or not (false).

Note that a bounding box that spans the globe from -180° (West, on the left) to +180° (East, on the right) is not considered to cross the International Date Line (which roughly follows the 180° longitude).

Default Value:
false

 

readonly  topLeft: {nokia.maps.geo.Coordinate}

This property holds an object containing geographic coordinates of the top left of the bounding box.

Method Details

contains(bbox): {Boolean}

This method checks if the object supplied by the caller lies within the area of the given bounding box. The object to check may either represent a point on the map or a bounding box.

Parameters:
 
bbox:
{nokia.maps.geo.Coordinate | nokia.maps.geo.BoundingBox}
 

An object representing a point on the map or a bounding box

Returns:
 
{Boolean}
A boolean value, true indicates that the object supplied by the caller is contained within the given bounding box, while false indicates that the received object is not contained within the bounding box

 

static  coverAll(coordinates): {nokia.maps.geo.BoundingBox}

This constructs a bounding box from an array of point objects (instances of Coordinate). If the method is successful, the caller receives the smallest bounding box that which contains all the points.

Parameters:
 
coordinates:
{nokia.maps.geo.ICoordinate[]}
 

An array of point objects (instances of Coordinate

Returns:
 
{nokia.maps.geo.BoundingBox}
 
 
The calculated bounding box

 

static  fromObject(obj, skipValidation): {nokia.maps.geo.BoundingBox}

This method constructs an instance of BoundingBox from a set of parameters supplied by the caller. The method accepts one parameter, which must be an array with four values top, left, bottom, right (lat, lng, lat,lng), or an array with two elements, each an instance of geo Coordinate. All latitude/longitude values must be given in decimal degrees (WGS84). The parameter can also be and innstance of BoundingBox.

Parameters:
 
obj:
{nokia.maps.geo.BoundingBox | Array}
 

An array containing two point objects (instances of Coordinate), or an array of four coordinates (lat, lng, lat, lng), or a bounding box

skipValidation:
{Boolean} [optional, default: false]
 

If true, then validation of latitude values is omitted when creating the bounding box; see also the constructor

Returns:
 
{nokia.maps.geo.BoundingBox}
 
 
The new geo bounding box or null if no bounding box could be created from the given parameter

 

static  fromPath(path, skipValidation): {nokia.maps.geo.BoundingBox}

This method constructs a bounding box from a Strip object that represents a path. The caller receives a bounding box object which contains the path.

Parameters:
 
path:
{nokia.maps.geo.Strip}
 

A Strip from which to create a bounding box object

skipValidation:
{Boolean} [optional]
 

A Boolean, if true, validation of latitude is omitted

Returns:
 
{nokia.maps.geo.BoundingBox}
 
 
The calculated geo bounding box

 

getCenter(): {nokia.maps.geo.Coordinate}

This method returns an object containing the coordinates of the center of the given bounding box.

Returns:
 
{nokia.maps.geo.Coordinate}
 
 
An instance of Coordinate representing the center of the bounding box on which the method has been called

 

getHeight(): {Number}

This method returns the height of the bounding box in decimal degrees.

Returns:
 
{Number}
The height of the bounding box in decimal degrees.

 

getWidth(): {Number}

This method returns the width of the bounding box in decimal degrees.

Returns:
 
{Number}
The width of the bounding box in decimal degrees.

 

intersects(bbox)

This method checks if the intersection of two bounding boxes is non-empty.

Parameters:
 
bbox:
{nokia.maps.geo.BoundingBox}
 

A BoundingBox object to be tested for intersection with the bounding box on which the method is called

Returns:
 
 
A {Boolean} indicating if the two bounding boxes intersect (true) or not (false)

 

isEmpty()

The method checks if the area enclosed by the given bounding box is 0.

Returns:
 
 
A {Boolean} indicating if the dimension of the bounding box is 0 (true) or not (false)

 

static  merge(boxes): {nokia.maps.geo.BoundingBox}

This method returns the smallest bounding box that covers all given boxes.

Parameters:
 
boxes:
{nokia.maps.geo.BoundingBox[]}
 

An array of BoundingBox instances to include in the new bounding box

Returns:
 
{nokia.maps.geo.BoundingBox}
 
 
A new instance of BoundingBox that contains the array of bounding boxes supplied by the caller

 

merge(boxes)

This method returns the smallest bounding box that covers the given bounding box and those supplied by the caller.

Parameters:
 
boxes:
{nokia.maps.geo.BoundingBox | nokia.maps.geo.BoundingBox[]}
 

An array of instance of BoundingBox

Returns:
 
 
An instance of {nokia.maps.geo.BoundingBox} representing the smallest rectangular area that includes the bounding box on which the method was called as well as the bounding boxes provided by the caller

 

resizeToCenter(center): {nokia.maps.geo.BoundingBox}

This method clones the given bounding box and resizes the clone if necessary until the location supplied by the caller is at its center.

Parameters:
 
center:
{nokia.maps.geo.Coordinate}
 

A point which is to be the center of the resized bounding box.

Returns:
 
{nokia.maps.geo.BoundingBox}
 
 
The resized bounding box