nokia.maps.geo.BoundingBox

Class Summary

This class represents a rectangular area defined in terms of the geographic coordinates its top-left and bottom-right corners.

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

Table 1. Property Summary
Properties

readonly  {nokia.maps.geo.Coordinate} bottomRight

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

readonly  {Boolean} isCDB

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

readonly  {nokia.maps.geo.Coordinate} topLeft

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

Table 2. Method Summary
Methods

contains (bbox)

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

type: {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

type: {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

type: {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  {nokia.maps.geo.Coordinate} bottomRight

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

readonly  {Boolean} isCDB

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  {nokia.maps.geo.Coordinate} topLeft

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

Method Details

contains(bbox)

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

type: {nokia.maps.geo.Coordinate | nokia.maps.geo.BoundingBox}

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

Returns:
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

type: {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

type: {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

type: {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

type: {nokia.maps.geo.Strip}

A Strip from which to create a bounding box object

skipValidation

type: {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

type: {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

type: {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

type: {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

type: {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
Parent topic: nokia.maps.geo