2gis-maps

<h2 id="basic-types">Basic Types</h2><p>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.</p> <p><dl class="api-incut"><ul class="page-contents"><li><a href="#dglatlng">DG.LatLng</a><ul><li><a href="#constructor">Constructor</a></li><li><a href="#methods">Methods</a></li><li><a href="#properties">Properties</a></li></ul></li><li><a href="#dglatlngbounds">DG.LatLngBounds</a><ul><li><a href="#creation">Creation</a></li><li><a href="#methods-1">Methods</a></li></ul></li><li><a href="#dgpoint">DG.Point</a><ul><li><a href="#creation-1">Creation</a></li><li><a href="#methods-2">Methods</a></li><li><a href="#properties-1">Properties</a></li></ul></li><li><a href="#dgbounds">DG.Bounds</a><ul><li><a href="#creation-2">Creation</a></li><li><a href="#methods-3">Methods</a></li><li><a href="#properties-2">Properties</a></li></ul></dl></p> <h3 id="dglatlng">DG.LatLng</h3><p>Represents a geographical point with a certain latitude and longitude.</p> <pre><code>var latlng = DG.latLng(54.98, 82.89); </code></pre><p>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:</p> <pre><code>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)); </code></pre><h4 id="constructor">Constructor</h4><table> <thead> <tr> <th>Factory</th> <th>Description</th> </tr> </thead> <tbody> <tr id="latlng-l-latlng"> <td><code><b>DG.latLng</b>( <nobr><Number> <i>latitude</i>,</nobr> <nobr><Number> <i>longitude</i>,</nobr> <nobr><Number> <i>altitude?</i> )</nobr> </code></td> <td>Creates an object representing a geographical point with the given latitude and longitude (and optionally altitude).</td> </tr> <tr> <td><code><b>DG.latLng</b>( <nobr><Array> <i>coords</i> )</nobr> </code></td> <td>Expects an array of the form <code>[Number, Number]</code> or <code>[Number, Number, Number]</code> instead.</td> </tr> <tr> <td><code><b>DG.latLng</b>( <nobr><Object> <i>coords</i> )</nobr> </code></td> <td>Expects an plain object of the form <code>{lat: Number, lng: Number}</code> or <code>{lat: Number, lng: Number, alt: Number}</code> instead.</td> </tr> </tbody> </table> <h4 id="methods">Methods</h4><table> <thead> <tr> <th>Method</th> <th>Returns</th> <th>Description</th> </tr> </thead> <tbody> <tr id="latlng-equals"> <td><code><b>equals</b>( <nobr><<a href="#dglatlng">LatLng</a>> <i>otherLatLng</i>,</nobr> <nobr><Number> <i>maxMargin?</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the given <a href="#dglatlng"><code>LatLng</code></a> point is at the same position (within a small margin of error). The margin of error can be overriden by setting <code>maxMargin</code> to a small number.</td> </tr> <tr id="latlng-tostring"> <td><code><b>toString</b>()</code></td> <td><code>String</code></td> <td>Returns a string representation of the point (for debugging purposes).</td> </tr> <tr id="latlng-distanceto"> <td><code><b>distanceTo</b>( <nobr><<a href="#dglatlng">LatLng</a>> <i>otherLatLng</i> )</nobr> </code></td> <td><code>Number</code></td> <td>Returns the distance (in meters) to the given <a href="#dglatlng"><code>LatLng</code></a> calculated using the <a href="http://en.wikipedia.org/wiki/Haversine_formula">Haversine formula</a>.</td> </tr> <tr id="latlng-wrap"> <td><code><b>wrap</b>()</code></td> <td><code><a href="#dglatlng">LatLng</a></code></td> <td>Returns a new <a href="#dglatlng"><code>LatLng</code></a> object with the longitude wrapped so it's always between -180 and +180 degrees.</td> </tr> <tr id="latlng-tobounds"> <td><code><b>toBounds</b>( <nobr><Number> <i>sizeInMeters</i> )</nobr> </code></td> <td><code><a href="#dglatlngbounds">LatLngBounds</a></code></td> <td>Returns a new <a href="#dglatlngbounds"><code>LatLngBounds</code></a> object in which each boundary is <code>sizeInMeters</code> meters apart from the <a href="#dglatlng"><code>LatLng</code></a>.</td> </tr> </tbody> </table> <h4 id="properties">Properties</h4><table> <thead> <tr> <th>Property</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr id="latlng-lat"> <td><code><b>lat</b></code></td> <td><code>Number</code></td> <td>Latitude in degrees.</td> </tr> <tr id="latlng-lng"> <td><code><b>lng</b></code></td> <td><code>Number</code></td> <td>Longitude in degrees.</td> </tr> <tr id="latlng-alt"> <td><code><b>alt</b></code></td> <td><code>Number</code></td> <td>Altitude in meters (optional).</td> </tr> </tbody> </table> <h3 id="dglatlngbounds">DG.LatLngBounds</h3><p>Represents a rectangular geographical area on a map.</p> <pre><code>var southWest = DG.latLng(54.9801, 82.8974), northEast = DG.latLng(54.9901, 82.9074), bounds = DG.latLngBounds(southWest, northEast); </code></pre><p>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:</p> <pre><code>map.fitBounds([ [54.9801, 82.8974], [54.9901, 82.9074] ]); </code></pre><h4 id="creation">Creation</h4><table> <thead> <tr> <th>Factory</th> <th>Description</th> </tr> </thead> <tbody> <tr id="latlngbounds-l-latlngbounds"> <td><code><b>DG.latLngBounds</b>( <nobr><<a href="#dglatlng">LatLng</a>> <i>southWest</i>,</nobr> <nobr><<a href="#dglatlng">LatLng</a>> <i>northEast</i> )</nobr> </code></td> <td>Creates a <a href="#dglatlngbounds"><code>LatLngBounds</code></a> object by defining south-west and north-east corners of the rectangle.</td> </tr> <tr> <td><code><b>DG.latLngBounds</b>( <nobr><LatLng[]> <i>latlngs</i>)</nobr> </code></td> <td>Creates a <a href="#dglatlngbounds"><code>LatLngBounds</code></a> object defined by the geographical points it contains. Very useful for zooming the map to fit a particular set of locations with <a href="/doc/maps/en/manual/map#map-fitbounds">fitBounds</a>.</td> </tr> </tbody> </table> <h4 id="methods-1">Methods</h4><table> <thead> <tr> <th>Method</th> <th>Returns</th> <th>Description</th> </tr> </thead> <tbody> <tr id="latlngbounds-extend"> <td><code><b>extend</b>( <nobr><<a href="#dglatlng">LatLng</a>> <i>latlng</i> )</nobr> </code></td> <td><code>this</code></td> <td>Extend the bounds to contain the given point.</td> </tr> <tr> <td><code><b>extend</b>( <nobr><<a href="#dglatlngbounds">LatLngBounds</a>> <i>otherBounds</i> )</nobr> </code></td> <td><code>this</code></td> <td>Extend the bounds to contain the given bounds.</td> </tr> <tr id="latlngbounds-pad"> <td><code><b>pad</b>( <nobr><Number> <i>bufferRatio</i> )</nobr> </code></td> <td><code><a href="#dglatlngbounds">LatLngBounds</a></code></td> <td>Returns bigger bounds created by extending the current bounds by a given percentage in each direction.</td> </tr> <tr id="latlngbounds-getcenter"> <td><code><b>getCenter</b>()</code></td> <td><code><a href="#dglatlng">LatLng</a></code></td> <td>Returns the center point of the bounds.</td> </tr> <tr id="latlngbounds-getsouthwest"> <td><code><b>getSouthWest</b>()</code></td> <td><code><a href="#dglatlng">LatLng</a></code></td> <td>Returns the south-west point of the bounds.</td> </tr> <tr id="latlngbounds-getnortheast"> <td><code><b>getNorthEast</b>()</code></td> <td><code><a href="#dglatlng">LatLng</a></code></td> <td>Returns the north-east point of the bounds.</td> </tr> <tr id="latlngbounds-getnorthwest"> <td><code><b>getNorthWest</b>()</code></td> <td><code><a href="#dglatlng">LatLng</a></code></td> <td>Returns the north-west point of the bounds.</td> </tr> <tr id="latlngbounds-getsoutheast"> <td><code><b>getSouthEast</b>()</code></td> <td><code><a href="#dglatlng">LatLng</a></code></td> <td>Returns the south-east point of the bounds.</td> </tr> <tr id="latlngbounds-getwest"> <td><code><b>getWest</b>()</code></td> <td><code>Number</code></td> <td>Returns the west longitude of the bounds.</td> </tr> <tr id="latlngbounds-getsouth"> <td><code><b>getSouth</b>()</code></td> <td><code>Number</code></td> <td>Returns the south latitude of the bounds.</td> </tr> <tr id="latlngbounds-geteast"> <td><code><b>getEast</b>()</code></td> <td><code>Number</code></td> <td>Returns the east longitude of the bounds.</td> </tr> <tr id="latlngbounds-getnorth"> <td><code><b>getNorth</b>()</code></td> <td><code>Number</code></td> <td>Returns the north latitude of the bounds.</td> </tr> <tr id="latlngbounds-contains"> <td><code><b>contains</b>( <nobr><<a href="#dglatlngbounds">LatLngBounds</a>> <i>otherBounds</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the rectangle contains the given one.</td> </tr> <tr id="latlngbounds-contains"> <td><code><b>contains</b>( <nobr><<a href="#dglatlng">LatLng</a>> <i>latlng</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the rectangle contains the given point.</td> </tr> <tr id="latlngbounds-intersects"> <td><code><b>intersects</b>( <nobr><<a href="#dglatlngbounds">LatLngBounds</a>> <i>otherBounds</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the rectangle intersects the given bounds. Two bounds intersect if they have at least one point in common.</td> </tr> <tr id="latlngbounds-overlaps"> <td><code><b>overlaps</b>( <nobr><<a href="#dgbounds">Bounds</a>> <i>otherBounds</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the rectangle overlaps the given bounds. Two bounds overlap if their intersection is an area.</td> </tr> <tr id="latlngbounds-tobboxstring"> <td><code><b>toBBoxString</b>()</code></td> <td><code>String</code></td> <td>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.</td> </tr> <tr id="latlngbounds-equals"> <td><code><b>equals</b>( <nobr><<a href="#dglatlngbounds">LatLngBounds</a>> <i>otherBounds</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the rectangle is equivalent (within a small margin of error) to the given bounds.</td> </tr> <tr id="latlngbounds-isvalid"> <td><code><b>isValid</b>()</code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the bounds are properly initialized.</td> </tr> </tbody> </table> <h3 id="dgpoint">DG.Point</h3><p>Represents a point with x and y coordinates in pixels.</p> <pre><code>var point = DG.point(200, 300); </code></pre><p>All methods and options that accept Point objects also accept them in a simple Array form (unless noted otherwise), so these lines are equivalent:</p> <pre><code>map.panBy([200, 300]); map.panBy(DG.point(200, 300)); </code></pre><h4 id="creation-1">Creation</h4><table> <thead> <tr> <th>Factory</th> <th>Description</th> </tr> </thead> <tbody> <tr id="point-l-point"> <td><code><b>DG.point</b>( <nobr><Number> <i>x</i>,</nobr> <nobr><Number> <i>y</i>,</nobr> <nobr><Boolean> <i>round?</i> )</nobr> </code></td> <td>Creates a Point object with the given <code>x</code> and <code>y</code> coordinates. If optional <code>round</code> is set to true, rounds the <code>x</code> and <code>y</code> values.</td> </tr> <tr id="point-l-point"> <td><code><b>DG.point</b>( <nobr><Number[]> <i>coords</i>)</nobr> </code></td> <td>Expects an array of the form <code>[x, y]</code> instead.</td> </tr> </tbody> </table> <h4 id="methods-2">Methods</h4><table> <thead> <tr> <th>Method</th> <th>Returns</th> <th>Description</th> </tr> </thead> <tbody> <tr id="point-clone"> <td><code><b>clone</b>()</nobr></code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns a copy of the current point.</td> </tr> <tr id="point-add"> <td><code><b>add</b>( <nobr><<a href="#dgpoint">Point</a>> <i>otherPoint</i> )</nobr> </code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns the result of addition of the current and the given points.</td> </tr> <tr id="point-subtract"> <td><code><b>subtract</b>( <nobr><<a href="#dgpoint">Point</a>> <i>otherPoint</i> )</nobr> </code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns the result of subtraction of the given point from the current.</td> </tr> <tr id="point-divideby"> <td><code><b>divideBy</b>( <nobr><Number> <i>num</i> )</nobr> </code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns the result of division of the current point by the given number.</td> </tr> <tr id="point-multiplyby"> <td><code><b>multiplyBy</b>( <nobr><Number> <i>num</i> )</nobr> </code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns the result of multiplication of the current point by the given number.</td> </tr> <tr id="point-scaleby"> <td><code><b>scaleBy</b>( <nobr><<a href="#dgpoint">Point</a>> <i>scale</i> )</nobr> </code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Multiply each coordinate of the current point by each coordinate of <code>scale</code>. In linear algebra terms, multiply the point by the <a href="https://en.wikipedia.org/wiki/Scaling_%28geometry%29#Matrix_representation">scaling matrix</a> defined by <code>scale</code>.</td> </tr> <tr id="point-unscaleby"> <td><code><b>unscaleBy</b>( <nobr><<a href="#dgpoint">Point</a>> <i>scale</i> )</nobr> </code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Inverse of <code>scaleBy</code>. Divide each coordinate of the current point by each coordinate of <code>scale</code>.</td> </tr> <tr id="point-round"> <td><code><b>round</b>()</code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns a copy of the current point with rounded coordinates.</td> </tr> <tr id="point-floor"> <td><code><b>floor</b>()</code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns a copy of the current point with floored coordinates (rounded down).</td> </tr> <tr id="point-ceil"> <td><code><b>ceil</b>()</code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns a copy of the current point with ceiled coordinates (rounded up).</td> </tr> <tr id="point-distanceto"> <td><code><b>distanceTo</b>( <nobr><<a href="#dgpoint">Point</a>> <i>otherPoint</i> )</nobr> </code></td> <td><code>Number</code></td> <td>Returns the cartesian distance between the current and the given points.</td> </tr> <tr id="point-equals"> <td><code><b>equals</b>( <nobr><<a href="#dgpoint">Point</a>> <i>otherPoint</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the given point has the same coordinates.</td> </tr> <tr id="point-contains"> <td><code><b>contains</b>( <nobr><<a href="#dgpoint">Point</a>> <i>otherPoint</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if both coordinates of the given point are less than the corresponding current point coordinates (in absolute values).</td> </tr> <tr id="point-tostring"> <td><code><b>toString</b>()</code></td> <td><code>String</code></td> <td>Returns a string representation of the point for debugging purposes.</td> </tr> </tbody> </table> <h4 id="properties-1">Properties</h4><table> <thead> <tr> <th>Property</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code><b>x</b></code></td> <td><code>Number</code></td> <td><code>x</code> coordinate.</td> </tr> <tr> <td><code><b>y</b></code></td> <td><code>Number</code></td> <td><code>y</code> coordinate.</td> </tr> </tbody> </table> <h3 id="dgbounds">DG.Bounds</h3><p>Represents a rectangular area in pixel coordinates.</p> <pre><code>var p1 = DG.point(10, 10), p2 = DG.point(40, 60), bounds = DG.bounds(p1, p2); </code></pre><p>All methods that accept <a href="#dgbounds"><code>Bounds</code></a> objects also accept them in a simple Array form (unless noted otherwise), so the bounds example above can be passed like this:</p></p> <pre><code>otherBounds.intersects([[10, 10], [40, 60]]); </code></pre><h4 id="creation-2">Creation</h4><table> <thead> <tr> <th>Factory</th> <th>Description</th> </tr> </thead> <tbody> <tr id="bounds-l-bounds"> <td><code><b>DG.bounds</b>( <nobr><<a href="#dgpoint">Point</a>> <i>topLeft</i>,</nobr> <nobr><<a href="#dgpoint">Point</a>> <i>bottomRight</i> )</nobr> </code></td> <td>Creates a Bounds object from two coordinates (usually top-left and bottom-right corners).</td> </tr> <tr id="bounds-l-bounds"> <td><code><b>DG.bounds</b>( <nobr><Point[]> <i>points</i> )</nobr> </code></td> <td>Creates a Bounds object from the points it contains.</td> </tr> </tbody> </table> <h4 id="methods-3">Methods</h4><table> <thead> <tr> <th>Method</th> <th>Returns</th> <th>Description</th> </tr> </thead> <tbody> <tr id="bounds-extend"> <td><code><b>extend</b>( <nobr><<a href="#dgpoint">Point</a>> <i>point</i> )</nobr> </code></td> <td><code>this</code></td> <td>Extends the bounds to contain the given point.</td> </tr> <tr id="bounds-getcenter"> <td><code><b>getCenter</b>( <nobr><Boolean> <i>round?</i> )</nobr> </code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns the center point of the bounds.</td> </tr> <tr id="bounds-getbottomleft"> <td><code><b>getBottomLeft</b>()</code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns the bottom-left point of the bounds.</td> </tr> <tr id="bounds-gettopright"> <td><code><b>getTopRight</b>()</code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns the top-right point of the bounds.</td> </tr> <tr id="bounds-getsize"> <td><code><b>getSize</b>()</code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>Returns the size of the given bounds.</td> </tr> <tr id="bounds-contains"> <td><code><b>contains</b>( <nobr><<a href="#dgbounds">Bounds</a>> <i>otherBounds</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the rectangle contains the given one.</td> </tr> <tr id="bounds-contains"> <td><code><b>contains</b>( <nobr><<a href="#dgpoint">Point</a>> <i>point</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the rectangle contains the given poing.</td> </tr> <tr id="bounds-intersects"> <td><code><b>intersects</b>( <nobr><<a href="#dgbounds">Bounds</a>> <i>otherBounds</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the rectangle intersects the given bounds. Two bounds intersect if they have at least one point in common.</td> </tr> <tr id="bounds-overlaps"> <td><code><b>overlaps</b>( <nobr><<a href="#dgbounds">Bounds</a>> <i>otherBounds</i> )</nobr> </code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the rectangle overlaps the given bounds. Two bounds overlap if their intersection is an area.</td> </tr> </tbody> </table> <h4 id="properties-2">Properties</h4><table> <thead> <tr> <th>Property</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr id="bounds-min"> <td><code><b>min</b></code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>The top left corner of the rectangle.</td> </tr> <tr id="bounds-max"> <td><code><b>max</b></code></td> <td><code><a href="#dgpoint">Point</a></code></td> <td>The bottom right corner of the rectangle.</td> </tr> </tbody> </table>