Basic Types

This section describes the classes of basic data types that are often found in the pages of maps API guide and required for use with many maps API objects.

DG.LatLng

Represents a geographical point with a certain latitude and longitude.

var latlng = DG.latLng(54.98, 82.89);

All methods that accept LatLng objects also accept them in a simple Array form and simple object form (unless noted otherwise), so these lines are equivalent:

map.panTo([54.98, 82.89]);
map.panTo({ lon: 82.89, lat: 54.98 });
map.panTo({ lat: 54.98, lng: 82.89 });
map.panTo(DG.latLng(54.98, 82.89));

Constructor

Factory	Description
`DG.latLng( <Number> latitude, <Number> longitude, <Number> altitude? )`	Creates an object representing a geographical point with the given latitude and longitude (and optionally altitude).
`DG.latLng( <Array> coords )`	Expects an array of the form `[Number, Number]` or `[Number, Number, Number]` instead.
`DG.latLng( <Object> coords )`	Expects an plain object of the form `{lat: Number, lng: Number}` or `{lat: Number, lng: Number, alt: Number}` instead.

Methods

Method	Returns	Description
`equals( <LatLng> otherLatLng, <Number> maxMargin? )`	`Boolean`	Returns `true` if the given `LatLng` point is at the same position (within a small margin of error). The margin of error can be overriden by setting `maxMargin` to a small number.
`toString()`	`String`	Returns a string representation of the point (for debugging purposes).
`distanceTo( <LatLng> otherLatLng )`	`Number`	Returns the distance (in meters) to the given `LatLng` calculated using the Haversine formula.
`wrap()`	`LatLng`	Returns a new `LatLng` object with the longitude wrapped so it's always between -180 and +180 degrees.
`toBounds( <Number> sizeInMeters )`	`LatLngBounds`	Returns a new `LatLngBounds` object in which each boundary is `sizeInMeters` meters apart from the `LatLng`.

Properties

Property	Type	Description
`lat`	`Number`	Latitude in degrees.
`lng`	`Number`	Longitude in degrees.
`alt`	`Number`	Altitude in meters (optional).

DG.LatLngBounds

Represents a rectangular geographical area on a map.

var southWest = DG.latLng(54.9801, 82.8974),
    northEast = DG.latLng(54.9901, 82.9074),
    bounds = DG.latLngBounds(southWest, northEast);

All methods that accept LatLngBounds objects also accept them in a simple Array form (unless noted otherwise), so the bounds example above can be passed like this:

map.fitBounds([
    [54.9801, 82.8974],
    [54.9901, 82.9074],
]);

Creation

Factory	Description
`DG.latLngBounds( <LatLng> southWest, <LatLng> northEast )`	Creates a `LatLngBounds` object by defining south-west and north-east corners of the rectangle.
`DG.latLngBounds( <LatLng[]> latlngs)`	Creates a `LatLngBounds` object defined by the geographical points it contains. Very useful for zooming the map to fit a particular set of locations with fitBounds.

Methods

Method	Returns	Description
`extend( <LatLng> latlng )`	`this`	Extend the bounds to contain the given point.
`extend( <LatLngBounds> otherBounds )`	`this`	Extend the bounds to contain the given bounds.
`pad( <Number> bufferRatio )`	`LatLngBounds`	Returns bigger bounds created by extending the current bounds by a given percentage in each direction.
`getCenter()`	`LatLng`	Returns the center point of the bounds.
`getSouthWest()`	`LatLng`	Returns the south-west point of the bounds.
`getNorthEast()`	`LatLng`	Returns the north-east point of the bounds.
`getNorthWest()`	`LatLng`	Returns the north-west point of the bounds.
`getSouthEast()`	`LatLng`	Returns the south-east point of the bounds.
`getWest()`	`Number`	Returns the west longitude of the bounds.
`getSouth()`	`Number`	Returns the south latitude of the bounds.
`getEast()`	`Number`	Returns the east longitude of the bounds.
`getNorth()`	`Number`	Returns the north latitude of the bounds.
`contains( <LatLngBounds> otherBounds )`	`Boolean`	Returns `true` if the rectangle contains the given one.
`contains( <LatLng> latlng )`	`Boolean`	Returns `true` if the rectangle contains the given point.
`intersects( <LatLngBounds> otherBounds )`	`Boolean`	Returns `true` if the rectangle intersects the given bounds. Two bounds intersect if they have at least one point in common.
`overlaps( <Bounds> otherBounds )`	`Boolean`	Returns `true` if the rectangle overlaps the given bounds. Two bounds overlap if their intersection is an area.
`toBBoxString()`	`String`	Returns a string with bounding box coordinates in a 'southwest_lng,southwest_lat,northeast_lng,northeast_lat' format. Useful for sending requests to web services that return geo data.
`equals( <LatLngBounds> otherBounds )`	`Boolean`	Returns `true` if the rectangle is equivalent (within a small margin of error) to the given bounds.
`isValid()`	`Boolean`	Returns `true` if the bounds are properly initialized.

DG.Point

Represents a point with x and y coordinates in pixels.

var point = DG.point(200, 300);

All methods and options that accept Point objects also accept them in a simple Array form (unless noted otherwise), so these lines are equivalent:

map.panBy([200, 300]);
map.panBy(DG.point(200, 300));

Creation

Factory	Description
`DG.point( <Number> x, <Number> y, <Boolean> round? )`	Creates a Point object with the given `x` and `y` coordinates. If optional `round` is set to true, rounds the `x` and `y` values.
`DG.point( <Number[]> coords)`	Expects an array of the form `[x, y]` instead.

Methods

Method	Returns	Description
`clone()`	`Point`	Returns a copy of the current point.
`add( <Point> otherPoint )`	`Point`	Returns the result of addition of the current and the given points.
`subtract( <Point> otherPoint )`	`Point`	Returns the result of subtraction of the given point from the current.
`divideBy( <Number> num )`	`Point`	Returns the result of division of the current point by the given number.
`multiplyBy( <Number> num )`	`Point`	Returns the result of multiplication of the current point by the given number.
`scaleBy( <Point> scale )`	`Point`	Multiply each coordinate of the current point by each coordinate of `scale`. In linear algebra terms, multiply the point by the scaling matrix defined by `scale`.
`unscaleBy( <Point> scale )`	`Point`	Inverse of `scaleBy`. Divide each coordinate of the current point by each coordinate of `scale`.
`round()`	`Point`	Returns a copy of the current point with rounded coordinates.
`floor()`	`Point`	Returns a copy of the current point with floored coordinates (rounded down).
`ceil()`	`Point`	Returns a copy of the current point with ceiled coordinates (rounded up).
`distanceTo( <Point> otherPoint )`	`Number`	Returns the cartesian distance between the current and the given points.
`equals( <Point> otherPoint )`	`Boolean`	Returns `true` if the given point has the same coordinates.
`contains( <Point> otherPoint )`	`Boolean`	Returns `true` if both coordinates of the given point are less than the corresponding current point coordinates (in absolute values).
`toString()`	`String`	Returns a string representation of the point for debugging purposes.

Properties

Property	Type	Description
`x`	`Number`	`x` coordinate.
`y`	`Number`	`y` coordinate.

DG.Bounds

Represents a rectangular area in pixel coordinates.

var p1 = DG.point(10, 10),
    p2 = DG.point(40, 60),
    bounds = DG.bounds(p1, p2);

All methods that accept Bounds objects also accept them in a simple Array form (unless noted otherwise), so the bounds example above can be passed like this:

otherBounds.intersects([
    [10, 10],
    [40, 60],
]);

Creation

Factory	Description
`DG.bounds( <Point> topLeft, <Point> bottomRight )`	Creates a Bounds object from two coordinates (usually top-left and bottom-right corners).
`DG.bounds( <Point[]> points )`	Creates a Bounds object from the points it contains.

Methods

Method	Returns	Description
`extend( <Point> point )`	`this`	Extends the bounds to contain the given point.
`getCenter( <Boolean> round? )`	`Point`	Returns the center point of the bounds.
`getBottomLeft()`	`Point`	Returns the bottom-left point of the bounds.
`getTopRight()`	`Point`	Returns the top-right point of the bounds.
`getSize()`	`Point`	Returns the size of the given bounds.
`contains( <Bounds> otherBounds )`	`Boolean`	Returns `true` if the rectangle contains the given one.
`contains( <Point> point )`	`Boolean`	Returns `true` if the rectangle contains the given poing.
`intersects( <Bounds> otherBounds )`	`Boolean`	Returns `true` if the rectangle intersects the given bounds. Two bounds intersect if they have at least one point in common.
`overlaps( <Bounds> otherBounds )`	`Boolean`	Returns `true` if the rectangle overlaps the given bounds. Two bounds overlap if their intersection is an area.

Properties

Property	Type	Description
`min`	`Point`	The top left corner of the rectangle.
`max`	`Point`	The bottom right corner of the rectangle.