View Source MapLibre (MapLibre v0.1.9)
Elixir bindings to MapLibre Style Specification.
A MapLibre style is a document that defines the visual appearance of a map: what data to draw, the order to draw it in, and how to style the data when drawing it. A style document is a JSON object with specific root level and nested properties. To learn more about the style specification and its properties, please see the documentation
Composing maps
Laying out a basic MapLibre map consists of the following steps:
alias MapLibre, as: Ml
# Initialize the specification with the initial style and optionally some other root properties.
# If you don't provide a initial style, the default style will be loaded for you
Ml.new(center: {-74.5, 40}, zoom: 6)
# Add sources to make their data available
|> Ml.add_source("rwanda-provinces",
type: :geojson,
data: "https://maplibre.org/maplibre-gl-js/docs/assets/rwanda-provinces.geojson"
)
# Add layers and refer them to sources to define their visual representation and make them visible
|> Ml.add_layer(id: "rwanda-provinces",
type: :fill,
source: "rwanda-provinces",
paint: [fill_color: "#4A9661"]
)
Expressions
Expressions are extremely powerful and useful to render complex data. To use them just ensure that you pass valid expressions following the rules and syntax of the official documentation
Options
To provide a more Elixir-friendly experience, the options are automatically normalized, so you can use keyword lists and snake-case atom keys.
Summary
Functions
Adds a GEO data to the sources in the specification.
Adds a data source by a given geocode to the sources in the specification.
Same as add_geocode_source/3
but for structured queries.
Adds a layer to the layers list in the specification.
Same as add_layer/2
but puts the given layer immediately below the labels
Adds a data source to the sources in the specification.
Adds points from tabular data to the sources in the specification.
Sets the glyphs url in the specification.
Sets the light options in the specification.
Adds or updates the map metadata properties. Metadata are arbitrary properties useful to track with the style, but do not influence rendering. Properties should be prefixed to avoid collisions, like "mapbox:".
Returns a style specification wrapped in the MapLibre
struct. If you don't provide a initial
style, the default style will be loaded for you. If
you wish to build a new style completely from scratch, pass an empty map %{}
as :style
option. The style specification version will be automatically set to 8.
Sets the sprite url in the specification.
Add 3D terrain to the map.
Returns the underlying MapLibre specification. The result is a nested Elixir data structure that serializes to MapLibre style JSON specification.
Defines a global default transition settings in the specification.
Updates a layer that was already defined in the specification
Types
@type coordinates_columns() :: {coordinates_format(), columns :: [String.t(), ...]}
@type coordinates_combined() :: {coordinates_format(), column :: String.t()}
@type coordinates_format() :: :lng_lat | :lat_lng
@type coordinates_spec() :: coordinates_combined() | coordinates_columns()
@type spec() :: map()
@type t() :: %MapLibre{spec: spec()}
Functions
Adds a GEO data to the sources in the specification.
For the :geojson
type, provides integration with the Geo
package.
geom = %Geo.LineString{coordinates: [
{-122.48369693756104, 37.83381888486939},
{-122.48348236083984, 37.83317489144141},
{-122.48339653015138, 37.83270036637107}
]}
Ml.new()
|> Ml.add_geo_source("route", geom)
Adds a data source by a given geocode to the sources in the specification.
For the :geojson
type, provides integration with Nominatim.
Any valid geocode is support in a free-form query string.
Ml.new()
|> Ml.add_geocode_source("brazil", "brazil")
|> Ml.add_geocode_source("pilkington-avenue", "pilkington avenue, birmingham")
Same as add_geocode_source/3
but for structured queries.
The last argument is an atom for the geocode type.
Supported types: :street
, :city
, :county
, :state
, :country
and :postalcode
Ml.new()
|> Ml.add_geocode_source("new-york", "new york", :city)
|> Ml.add_geocode_source("ny", "new york", :state)
Adds a layer to the layers list in the specification.
A style's layers property lists all the layers available in the style. The type of layer is
specified by the :type
property, and must be one of :background
, :fill
, :line
,
:symbol
, :raster
, :circle
, :fill_extrusion
, :heatmap
, :hillshade
.
Except for layers of the :background
type, each layer needs to refer to a source. Layers take
the data that they get from a source, optionally filter features, and then define how those
features are styled.
Required
:id
- Unique layer name.:type
- One of::fill
- A filled polygon with an optional stroked border.:line
- A stroked line.:symbol
- An icon or a text label.:circle
- A filled circle.:heatmap
- A heatmap.:fill_extrusion
- An extruded (3D) polygon.:raster
- Raster map textures such as satellite imagery.:hillshade
- Client-side hillshading visualization based on DEM data.:background
- The background color or pattern of the map.
:source
- Name of a source description to be used for the layer. Required for all layer types except:background
.
Options
:filter
- A expression specifying conditions on source features. Only features that match the filter are displayed.:layout
- Layout properties for the layer.:maxzoom
- Optional number between 0 and 24 inclusive. The maximum zoom level for the layer. At zoom levels equal to or greater than the:maxzoom
, the layer will be hidden:metadata
- Arbitrary properties useful to track with the layer, but do not influence rendering. Properties should be prefixed to avoid collisions:minzoom
- Optional number between 0 and 24 inclusive. The minimum zoom level for the layer. At zoom levels less than the:minzoom
, the layer will be hidden.:paint
- Default paint properties for this layer.
Type specific
:source_layer
- Layer to use from a vector tile source. Required for vector tile sources; prohibited for all other source types, including GeoJSON sources.
Examples
|> Ml.add_layer(id: "rwanda-provinces",
type: :fill,
source: "rwanda-provinces",
paint: [fill_color: "#4A9661"]
)
See the docs for more details.
Same as add_layer/2
but puts the given layer immediately below the labels
Adds a data source to the sources in the specification.
Sources state which data the map should display. Specify the type of source with the :type
property, which must be one of :vector
, :raster
, :raster_dem
, :geojson
, :image
or :video
.
Examples
Ml.new()
|> Ml.add_source("rwanda-provinces",
type: :geojson,
data: "https://maplibre.org/maplibre-gl-js/docs/assets/rwanda-provinces.geojson"
)
See the docs for more details.
Adds points from tabular data to the sources in the specification.
For the :geojson
type, provides integration with tabular data that implements the
Table protocol.
Supports data where the coordinates information is either in distinct columns or combined in a
single one. In both cases you need to provide the pattern followed by the coordinates data:
:lng_lat
or :lat_lng
Properties are also supported as a list of columns in the options.
earthquakes = %{
"latitude" => [32.3646, 32.3357, -9.0665, 52.0779, -57.7326],
"longitude" => [101.8781, 101.8413, -71.2103, 178.2851, 148.6945],
"mag" => [5.9, 5.6, 6.5, 6.3, 6.4]
}
Ml.new()
|> Ml.add_table_source("earthquakes", earthquakes, {:lng_lat, ["longitude", "latitude"]})
earthquakes = %{
"coordinates" => ["32.3646, 101.8781", "32.3357, 101.8413", "-9.0665, -71.2103"],
"mag" => [5.9, 5.6, 6.5]
}
Ml.new()
|> Ml.add_table_source("earthquakes", earthquakes, {:lat_lng, "coordinates"}, properties: ["mag"])
Sets the glyphs url in the specification.
A style's glyphs property provides a URL template for loading signed-distance-field glyph sets in PBF format.
See the docs for more details.
Sets the light options in the specification.
A style's light property provides a global light source for that style. Since this property is the light used to light extruded features, you will only see visible changes to your map style when modifying this property if you are using extrusions.
Options
:anchor
- Whether extruded geometries are lit relative to the map or viewport. "map": The position of the light source is aligned to the rotation of the map. "viewport": The position of the light source is aligned to the rotation of the viewport. Default: "viewport":color
- Color tint for lighting extruded geometries. Default: "#ffffff":intensity
- Intensity of lighting (on a scale from 0 to 1). Higher numbers will present as more extreme contrast. Default: 0.5:position
- Position of the light source relative to lit (extruded) geometries, in {r radial coordinate, a azimuthal angle, p polar angle} where r indicates the distance from the center of the base of an object to its light, a indicates the position of the light relative to 0° (0° when light.anchor is set to viewport corresponds to the top of the viewport, or 0° when light.anchor is set to map corresponds to due north, and degrees proceed clockwise), and p indicates the height of the light (from 0°, directly above, to 180°, directly below). Default: {1.15, 210, 30}
See the docs for more details.
Adds or updates the map metadata properties. Metadata are arbitrary properties useful to track with the style, but do not influence rendering. Properties should be prefixed to avoid collisions, like "mapbox:".
Returns a style specification wrapped in the MapLibre
struct. If you don't provide a initial
style, the default style will be loaded for you. If
you wish to build a new style completely from scratch, pass an empty map %{}
as :style
option. The style specification version will be automatically set to 8.
Options
Only the following properties are allowed directly on new/1
:bearing
- Default bearing, in degrees. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up. This value will be used only if the map has not been positioned by other means (e.g. map options or user interaction). Default: 0:center
- Default map center in longitude and latitude. The style center will be used only if the map has not been positioned by other means (e.g. map options or user interaction). Default: {0, 0}:name
- A human-readable name for the style.:pitch
- Default pitch, in degrees. Zero is perpendicular to the surface, for a look straight down at the map, while a greater value like 60 looks ahead towards the horizon. The style pitch will be used only if the map has not been positioned by other means (e.g. map options or user interaction). Default: 0:zoom
- Default zoom level. The style zoom will be used only if the map has not been positioned by other means (e.g. map options or user interaction).:style
- The initial style specification. Three built-in initial styles are available::default
,:street
and:terrain
.:key
- The Maptiler key to be used by the built-in:street
and:terrain
styles. If you don't provide a key, the default key (strictly for non-commercial use) will be used.
To manipulate any other style root properties, use the corresponding functions
Examples
Ml.new(
center: {-74.5, 40},
zoom: 9,
name: "Rwanda population density"
)
|> ...
See the docs for more details.
Sets the sprite url in the specification.
A style's sprite property supplies a URL template for loading small images to use in rendering
:background_pattern
, :fill_pattern
, :line_pattern
,:fill_extrusion_pattern
and :icon_image
style
properties.
See the docs for more details.
Add 3D terrain to the map.
The source must have been previously added to the map.
See the docs for more details.
Returns the underlying MapLibre specification. The result is a nested Elixir data structure that serializes to MapLibre style JSON specification.
See the docs for more details.
Defines a global default transition settings in the specification.
A transition property controls timing for the interpolation between a transitionable style property's previous value and new value. A style's root transition property provides global transition defaults for that style.
See the docs for more details.
Updates a layer that was already defined in the specification