Component API calls

petewarden edited this page Sep 14, 2010 · 25 revisions

These are the functions you can call on an OpenHeatMap object from Javascript within a page. The object itself should be retrieved by calling getOpenHeatMap() from the supplied openheatmap.js script.

addInlay(leftX, topY, rightX, bottomY, topLat, leftLon, bottomLat, rightLon)

addPopup(latitude, longitude, html)

bind(eventName, functionName)

getAllInlays()

getLatLonViewingArea()

getPixelsPerDegreeLatitude()

getValueForWayId(wayId)

getValueHeaders()

getValuePointsNearLatLon(latitude, longitude, radius=0)

getWayForWayId(wayId)

getWaysContainingLatLon(latitude, longitude)

loadValuesFromCSVString(csvString)

loadValuesFromFile(url)

loadWaysFromFile(url)

removeAllInlays()

removeAllPopups()

removeAllWays()

setColorGradient(gradient: [])

setGradientValueRange(minimum, maximum)

setLatLonViewingArea(topLat, leftLon, bottomLat, rightLon)

setOceanColor(color)

setPixelsPerDegreeLatitude(pixelsPerDegree)

setSetting(key, value)

setSize(width, height)

setWayDefault(key, value)

translateMapByScreenPixels(x, y)

addInlay(leftX, topY, rightX, bottomY, topLat, leftLon, bottomLat, rightLon)

Creates an inlay that renders an area of the map over the top of the main view. This is typically used to display places like Alaska or Hawaii on a map of the US, but is also useful for showing details like a zoomed-in view of a city center on a regional map. One pitfall to beware of is that the first four values are coordinates in screen pixels for the area where the inlay should appear in the current view, so you should only call this directly after setting the initial viewing area, before the user has had a chance to zoom and pan.

addPopup(latitude, longitude, html)

Creates a popup at the specified location on the map, containing the styled text you specify in the html parameter. This popup will not move when the user pans or zooms, so you should call removeAllPopups() when you detect these user events if you’ve created any popups.

bind(eventName, functionName)

Tells the component to call the user-supplied function whenever the specified event occurs. The second argument should be a string not a direct reference to a function, to keep compatibility with the Flash version of the renderer. For a full description of the possible events see Events list. For example, you could call $.getOpenHeatMap().bind(‘onerror’, ‘myOnErrorFunction’);

getAllInlays()
returns [{ left_x:, top_y:, right_x:, bottom_y, top_lat: , left_lon: , bottom_lat: , right_lon: }, …]

Returns the definitions of the current inlays, with the coordinates translated to the correct position on the main map if the user has panned or zoomed the view since they were initially added. As with addInlay(), there’s a lot of potential for confusion thanks to the use of screen-space coordinates for the positioning of the inlay on the main map.

getLatLonViewingArea()
returns { topLat: , leftLon: , bottomLat: , rightLon: }

Returns the latitude and longitude at the corners of the current viewing area. If the user hasn’t panned or zoomed, these should be identical to the values previously set with setLatLonViewingArea, otherwise they’ll reflect the user’s changes.

getPixelsPerDegreeLatitude()
returns Number

The result of the function is the vertical scale factor of the current view. For example, if it’s 4.0, then you’d need a map (4*180) or 720 pixels high to represent the full range of latitudes from Antarctica to the North Pole. Because latitudes increase as you head north, and the component uses a vertical axis where zero is at the top and larger values represent lower pixels, this is usually a negative value.

getValueForWayId(wayId)
returns Number | null

If the map is displaying data specifying values for individual areas, then this function will return the value associated with a particular area. The input ID is typically received from an event callback telling you which ways the user is mousing over. If the map is animated then the value will be from the current frame being displayed. If no value is set, then null will be returned.

getValueHeaders()
returns [“header_name”, …]

Returns a list of the column names of the currently loaded data, as an array of strings. This can be useful if you want to figure out what data to display as the user mouses over an area, by understanding how the underlying data values were input (eg by state or county).

getValuePointsNearLatLon(latitude, longitude, radius=0)
returns [{value: }, …]

If the map is displaying data as a density map of individual points, this will return an array containing the values of points within the radius of the specified point. If no points are nearby, it will return an empty array.

getWayForWayId(wayId)
returns {id: , nds: [], tags: {} }

Given the identifier of a way, this will return the full information for that way. This closely follows the OpenStreetMap XML format, with the nds array specifying nodes within the main list, and tags containing the key/value pairs holding information about the way. This can be useful if you want to pull common tags like ‘name’ for a node that the user is mousing over.

getWaysContainingLatLon(latitude, longitude)
returns [{id: , nds: [], tags: {} }, …]

Returns a list of the ways that this point lies within. For closed polygons (where the last node is the same as the first, and drawn as a filled area) this accomplished with a simple intersection test. For unclosed polygons (where the last node is not the first, and drawn as a series of connected lines) the test is done against a thick line, with the thickness controlled by the line_thickness property of the way. The format of each way in the list is the same as for getWayForWayId()

loadValuesFromCSVString(csvString)

Use this function to load in values to display on the map from a string containing a header row of labels separated by commas, followed by a newline, then a series of rows specifying values for each label with each value separated by commas and each row separated from the next by a newline. The labels should include a location header (see What kind of locations does OpenHeatMap understand? ) and possibly a value and other columns.

loadValuesFromFile(url)

This function is identical to loadValuesFromCSVString() except that it loads the values from the network resource specified by the input URL rather than directly from a string containing the data.

loadWaysFromFile(url)

Loads the polygons and lines that define the map. The file should be in the OpenStreetMap XML format, and if you want to color the different areas using values from the data you’ll need to include key/value pairs in the tags that correspond to location headers in the data. For example if you create an OSM XML file containing the areas covered by each US zip code, and you have a CSV file with ‘zipcode’ as one of the columns, then your ways will need to identify them.

removeAllInlays()

Gets rid of all the inlays in the current map. You should call this to reset the map if you’re switching over to a completely new view, to remove any inlays left over from the previous one.

removeAllPopups()

Gets rid of all the popups on the current map.

removeAllWays()

Deletes all the current polygons and lines from the map. You’ll usually call this before you load a new set of ways into an existing map.

setColorGradient(gradient: [])

Sets the color scale used to display the values on the map. It’s specified as a variable length array of color strings, eg setColorGradient([‘#000000’, ‘#FFFFFF’]); will create a black-to-white gradient. To control

setGradientValueRange(minimum, maximum)

Normally the color to use for an area is worked out by stretching the gradient colors between the maximum and minimum values in the input data. Sometimes you’ll want to ignore a few very high or low values, so this function lets you override the automatic range and specify a smaller one to display. For example, if you want to concentrate on the range 0 to 20 in your values, you’d call setGradientValueRange(0, 20)

setLatLonViewingArea(topLat, leftLon, bottomLat, rightLon)

Defines the area of the map that will be initially shown within the component. The aspect ratio of this display is unconstrained, so you can end up with visibly distorted maps if you stretch the horizontal or vertical values too much.

setOceanColor(color)

Sets the background color of the map, used for any areas not covered by way polygons. This is specified as a number, not the usual html string, eg it’s 0xffffff not #ffffff. Yes, this is inconsistent, I’ll update it to accept strings in a future release whilst keeping compatibility with the current behavior.

setPixelsPerDegreeLatitude(pixelsPerDegree)

Sets the scale factor for the map. See getPixelsPerDegree() for an explanation of the units.

setSetting(key, value)

Call this to control the behavior of the map through configurable settings. For a complete list of the names and possible values of these settings see the Map settings reference

setSize(width, height)

Controls the dimensions of the map.

setWayDefault(key, value)

This defines what values are used for keys that are unset in a particular way. The most common example is ‘color’; if an area doesn’t have a value associated with it then the default value for the key ‘color’ will be used instead. You can call this function to change what that default is for various values. Here’s the current ones that are meaningful:
color – defaults to 0×000000
alpha – defaults to 1.0
line_thickness – defaults to 0 (hair-line thickness)

translateMapByScreenPixels(x, y)

Moves the viewing area of the map. The translation amount is specified in pixels at the current viewing scale.