OpenLayers.Bounds

Instances of this class represent bounding boxes.  Data stored as left, bottom, right, top floats.  All values are initialized to null, however, you should make sure you set them before using the bounds for anything.

Possible use case

bounds = new OpenLayers.Bounds();
bounds.extend(new OpenLayers.LonLat(4,5));
bounds.extend(new OpenLayers.LonLat(5,6));
bounds.toBBOX(); // returns 4,5,5,6
Summary
OpenLayers.BoundsInstances of this class represent bounding boxes.
Properties
left{Number} Minimum horizontal coordinate.
bottom{Number} Minimum vertical coordinate.
right{Number} Maximum horizontal coordinate.
top{Number} Maximum vertical coordinate.
centerLonLat{OpenLayers.LonLat} A cached center location.
Constructor
OpenLayers.BoundsConstruct a new bounds object.
Functions
cloneCreate a cloned instance of this bounds.
equalsTest a two bounds for equivalence.
toStringReturns a string representation of the bounds object.
toArrayReturns an array representation of the bounds object.
toBBOXReturns a boundingbox-string representation of the bounds object.
toGeometryCreate a new polygon geometry based on this bounds.
getWidthReturns the width of the bounds.
getHeightReturns the height of the bounds.
getSizeReturns an OpenLayers.Size object of the bounds.
getCenterPixelReturns the OpenLayers.Pixel object which represents the center of the bounds.
getCenterLonLatReturns the OpenLayers.LonLat object which represents the center of the bounds.
scaleScales the bounds around a pixel or lonlat.
addShifts the coordinates of the bound by the given horizontal and vertical deltas.
extendExtend the bounds to include the OpenLayers.LonLat, OpenLayers.Geometry.Point or OpenLayers.Bounds specified.
extendXYExtend the bounds to include the XY coordinate specified.
containsLonLatReturns whether the bounds object contains the given OpenLayers.LonLat.
containsPixelReturns whether the bounds object contains the given OpenLayers.Pixel.
containsReturns whether the bounds object contains the given x and y.
intersectsBoundsDetermine whether the target bounds intersects this bounds.
containsBoundsReturns whether the bounds object contains the given OpenLayers.Bounds.
determineQuadrantReturns the the quadrant (“br”, “tr”, “tl”, “bl”) in which the given OpenLayers.LonLat lies.
transformTransform the Bounds object from source to dest.
fromStringAlternative constructor that builds a new OpenLayers.Bounds from a parameter string.
fromArrayAlternative constructor that builds a new OpenLayers.Bounds from an array.
fromSizeAlternative constructor that builds a new OpenLayers.Bounds from a size.
oppositeQuadrantGet the opposite quadrant for a given quadrant string.

Properties

left

{Number} Minimum horizontal coordinate.

bottom

{Number} Minimum vertical coordinate.

right

{Number} Maximum horizontal coordinate.

top

{Number} Maximum vertical coordinate.

centerLonLat

{OpenLayers.LonLat} A cached center location.  This should not be accessed directly.  Use getCenterLonLat instead.

Constructor

OpenLayers.Bounds

Construct a new bounds object.  Coordinates can either be passed as four arguments, or as a single argument.

Parameters (four arguments)

left{Number} The left bounds of the box.  Note that for width calculations, this is assumed to be less than the right value.
bottom{Number} The bottom bounds of the box.  Note that for height calculations, this is assumed to be less than the top value.
right{Number} The right bounds.
top{Number} The top bounds.

Parameters (single argument)

bounds{Array(Number)} [left, bottom, right, top]

Functions

clone

clone:function()

Create a cloned instance of this bounds.

Returns

{OpenLayers.Bounds} A fresh copy of the bounds

equals

equals:function(bounds)

Test a two bounds for equivalence.

Parameters

bounds{OpenLayers.Bounds}

Returns

{Boolean} The passed-in bounds object has the same left, right, top, bottom components as this.  Note that if bounds passed in is null, returns false.

toString

toString:function()

Returns a string representation of the bounds object.

Returns

{String} String representation of bounds object.

toArray

toArray: function(reverseAxisOrder)

Returns an array representation of the bounds object.

Returns an array of left, bottom, right, top properties, or -- when the optional parameter is true -- an array of the bottom, left, top, right properties.

Parameters

reverseAxisOrder{Boolean} Should we reverse the axis order?

Returns

{Array} array of left, bottom, right, top

toBBOX

toBBOX:function(decimal,
reverseAxisOrder)

Returns a boundingbox-string representation of the bounds object.

Parameters

decimal{Integer} How many decimal places in the bbox coords?  Default is 6
reverseAxisOrder{Boolean} Should we reverse the axis order?

Returns

{String} Simple String representation of bounds object.  (e.g.  “5,42,10,45”)

toGeometry

toGeometry: function()

Create a new polygon geometry based on this bounds.

Returns

{OpenLayers.Geometry.Polygon} A new polygon with the coordinates of this bounds.

getWidth

getWidth:function()

Returns the width of the bounds.

Returns

{Float} The width of the bounds (right minus left).

getHeight

getHeight:function()

Returns the height of the bounds.

Returns

{Float} The height of the bounds (top minus bottom).

getSize

getSize:function()

Returns an OpenLayers.Size object of the bounds.

Returns

{OpenLayers.Size} The size of the bounds.

getCenterPixel

getCenterPixel:function()

Returns the OpenLayers.Pixel object which represents the center of the bounds.

Returns

{OpenLayers.Pixel} The center of the bounds in pixel space.

getCenterLonLat

getCenterLonLat:function()

Returns the OpenLayers.LonLat object which represents the center of the bounds.

Returns

{OpenLayers.LonLat} The center of the bounds in map space.

scale

scale: function(ratio,
origin)

Scales the bounds around a pixel or lonlat.  Note that the new bounds may return non-integer properties, even if a pixel is passed.

Parameters

ratio{Float}
origin{OpenLayers.Pixel or OpenLayers.LonLat} Default is center.

Returns

{OpenLayers.Bounds} A new bounds that is scaled by ratio from origin.

add

add:function(x,
y)

Shifts the coordinates of the bound by the given horizontal and vertical deltas.

var bounds = new OpenLayers.Bounds(0, 0, 10, 10);
bounds.toString();
// => "0,0,10,10"

bounds.add(-1.5, 4).toString();
// => "-1.5,4,8.5,14"

This method will throw a TypeError if it is passed null as an argument.

Parameters

x{Float} horizontal delta
y{Float} vertical delta

Returns

{OpenLayers.Bounds} A new bounds whose coordinates are the same as this, but shifted by the passed-in x and y values.

extend

extend:function(object)

Extend the bounds to include the OpenLayers.LonLat, OpenLayers.Geometry.Point or OpenLayers.Bounds specified.

Please note that this function assumes that left < right and bottom < top.

Parameters

object{OpenLayers.LonLat, OpenLayers.Geometry.Point or OpenLayers.Bounds} The object to be included in the new bounds object.

extendXY

extendXY:function(x,
y)

Extend the bounds to include the XY coordinate specified.

Parameters

x{number} The X part of the the coordinate.
y{number} The Y part of the the coordinate.

containsLonLat

containsLonLat: function(ll,
options)

Returns whether the bounds object contains the given OpenLayers.LonLat.

Parameters

ll{<OpenLayers.LonLat>|Object} OpenLayers.LonLat or an object with a ‘lon’ and ‘lat’ properties.
options{Object} Optional parameters

Acceptable options

inclusive{Boolean} Whether or not to include the border.  Default is true.
worldBounds{OpenLayers.Bounds} If a worldBounds is provided, the ll will be considered as contained if it exceeds the world bounds, but can be wrapped around the dateline so it is contained by this bounds.

Returns

{Boolean} The passed-in lonlat is within this bounds.

containsPixel

containsPixel:function(px,
inclusive)

Returns whether the bounds object contains the given OpenLayers.Pixel.

Parameters

px{OpenLayers.Pixel}
inclusive{Boolean} Whether or not to include the border.  Default is true.

Returns

{Boolean} The passed-in pixel is within this bounds.

contains

contains:function(x,
y,
inclusive)

Returns whether the bounds object contains the given x and y.

Parameters

x{Float}
y{Float}
inclusive{Boolean} Whether or not to include the border.  Default is true.

Returns

{Boolean} Whether or not the passed-in coordinates are within this bounds.

intersectsBounds

intersectsBounds:function(bounds,
options)

Determine whether the target bounds intersects this bounds.  Bounds are considered intersecting if any of their edges intersect or if one bounds contains the other.

Parameters

bounds{OpenLayers.Bounds} The target bounds.
options{Object} Optional parameters.

Acceptable options

inclusive{Boolean} Treat coincident borders as intersecting.  Default is true.  If false, bounds that do not overlap but only touch at the border will not be considered as intersecting.
worldBounds{OpenLayers.Bounds} If a worldBounds is provided, two bounds will be considered as intersecting if they intersect when shifted to within the world bounds.  This applies only to bounds that cross or are completely outside the world bounds.

Returns

{Boolean} The passed-in bounds object intersects this bounds.

containsBounds

containsBounds:function(bounds,
partial,
inclusive)

Returns whether the bounds object contains the given OpenLayers.Bounds.

bounds{OpenLayers.Bounds} The target bounds.
partial{Boolean} If any of the target corners is within this bounds consider the bounds contained.  Default is false.  If false, the entire target bounds must be contained within this bounds.
inclusive{Boolean} Treat shared edges as contained.  Default is true.

Returns

{Boolean} The passed-in bounds object is contained within this bounds.

determineQuadrant

determineQuadrant: function(lonlat)

Returns the the quadrant (“br”, “tr”, “tl”, “bl”) in which the given OpenLayers.LonLat lies.

Parameters

lonlat{OpenLayers.LonLat}

Returns

{String} The quadrant (“br” “tr” “tl” “bl”) of the bounds in which the coordinate lies.

transform

transform: function(source,
dest)

Transform the Bounds object from source to dest.

Parameters

source{OpenLayers.Projection} Source projection.
dest{OpenLayers.Projection} Destination projection.

Returns

{OpenLayers.Bounds} Itself, for use in chaining operations.

fromString

OpenLayers.Bounds.fromString = function(str,
reverseAxisOrder)

Alternative constructor that builds a new OpenLayers.Bounds from a parameter string.

OpenLayers.Bounds.fromString("5,42,10,45");
// => equivalent to ...
new OpenLayers.Bounds(5, 42, 10, 45);

Parameters

str{String} Comma-separated bounds string.  (e.g.  “5,42,10,45”)
reverseAxisOrder{Boolean} Does the string use reverse axis order?

Returns

{OpenLayers.Bounds} New bounds object built from the passed-in String.

fromArray

OpenLayers.Bounds.fromArray = function(bbox,
reverseAxisOrder)

Alternative constructor that builds a new OpenLayers.Bounds from an array.

OpenLayers.Bounds.fromArray( [5, 42, 10, 45] );
// => equivalent to ...
new OpenLayers.Bounds(5, 42, 10, 45);

Parameters

bbox{Array(Float)} Array of bounds values (e.g.  [5,42,10,45])
reverseAxisOrder{Boolean} Does the array use reverse axis order?

Returns

{OpenLayers.Bounds} New bounds object built from the passed-in Array.

fromSize

OpenLayers.Bounds.fromSize = function(size)

Alternative constructor that builds a new OpenLayers.Bounds from a size.

OpenLayers.Bounds.fromSize( new OpenLayers.Size(10, 20) );
// => equivalent to ...
new OpenLayers.Bounds(0, 20, 10, 0);

Parameters

size{OpenLayers.Size or Object} OpenLayers.Size or an object with both ‘w’ and ‘h’ properties.

Returns

{OpenLayers.Bounds} New bounds object built from the passed-in size.

oppositeQuadrant

OpenLayers.Bounds.oppositeQuadrant = function(quadrant)

Get the opposite quadrant for a given quadrant string.

OpenLayers.Bounds.oppositeQuadrant( "tl" );
// => "br"

OpenLayers.Bounds.oppositeQuadrant( "tr" );
// => "bl"

Parameters

quadrant{String} two character quadrant shortstring

Returns

{String} The opposing quadrant (“br” “tr” “tl” “bl”).  For Example, if you pass in “bl” it returns “tr”, if you pass in “br” it returns “tl”, etc.

This class represents a longitude and latitude pair
clone:function()
Create a cloned instance of this bounds.
equals:function(bounds)
Test a two bounds for equivalence.
toString:function()
Returns a string representation of the bounds object.
toArray: function(reverseAxisOrder)
Returns an array representation of the bounds object.
toBBOX:function(decimal,
reverseAxisOrder)
Returns a boundingbox-string representation of the bounds object.
toGeometry: function()
Create a new polygon geometry based on this bounds.
getWidth:function()
Returns the width of the bounds.
getHeight:function()
Returns the height of the bounds.
getSize:function()
Returns an OpenLayers.Size object of the bounds.
Instances of this class represent a width/height pair
getCenterPixel:function()
Returns the OpenLayers.Pixel object which represents the center of the bounds.
This class represents a screen coordinate, in x and y coordinates
getCenterLonLat:function()
Returns the OpenLayers.LonLat object which represents the center of the bounds.
scale: function(ratio,
origin)
Scales the bounds around a pixel or lonlat.
add:function(x,
y)
Shifts the coordinates of the bound by the given horizontal and vertical deltas.
extend:function(object)
Extend the bounds to include the OpenLayers.LonLat, OpenLayers.Geometry.Point or OpenLayers.Bounds specified.
Point geometry class.
Construct a new bounds object.
extendXY:function(x,
y)
Extend the bounds to include the XY coordinate specified.
containsLonLat: function(ll,
options)
Returns whether the bounds object contains the given OpenLayers.LonLat.
containsPixel:function(px,
inclusive)
Returns whether the bounds object contains the given OpenLayers.Pixel.
contains:function(x,
y,
inclusive)
Returns whether the bounds object contains the given x and y.
intersectsBounds:function(bounds,
options)
Determine whether the target bounds intersects this bounds.
containsBounds:function(bounds,
partial,
inclusive)
Returns whether the bounds object contains the given OpenLayers.Bounds.
determineQuadrant: function(lonlat)
Returns the the quadrant (“br”, “tr”, “tl”, “bl”) in which the given OpenLayers.LonLat lies.
transform: function(source,
dest)
Transform the Bounds object from source to dest.
OpenLayers.Bounds.fromString = function(str,
reverseAxisOrder)
Alternative constructor that builds a new OpenLayers.Bounds from a parameter string.
OpenLayers.Bounds.fromArray = function(bbox,
reverseAxisOrder)
Alternative constructor that builds a new OpenLayers.Bounds from an array.
OpenLayers.Bounds.fromSize = function(size)
Alternative constructor that builds a new OpenLayers.Bounds from a size.
OpenLayers.Bounds.oppositeQuadrant = function(quadrant)
Get the opposite quadrant for a given quadrant string.
Polygon is a collection of Geometry.LinearRings.
Methods for coordinate transforms between coordinate systems.
Close