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.

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(), ...]}
Link to this type

coordinates_combined()

View Source
@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

Link to this function

add_geo_source(ml, source, geom, opts \\ [])

View Source
@spec add_geo_source(t(), String.t(), struct(), keyword()) :: t()

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)
Link to this function

add_geocode_source(ml, source, query)

View Source
@spec add_geocode_source(t(), String.t(), String.t()) :: t()

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")
Link to this function

add_geocode_source(ml, source, query, type)

View Source
@spec add_geocode_source(t(), String.t(), String.t(), atom()) :: t()

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)
@spec add_layer(
  t(),
  keyword()
) :: t()

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.

Link to this function

add_layer_below_labels(ml, opts)

View Source
@spec add_layer_below_labels(
  t(),
  keyword()
) :: t()

Same as add_layer/2 but puts the given layer immediately below the labels

Link to this function

add_source(ml, source, opts)

View Source
@spec add_source(t(), String.t(), keyword()) :: t()

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.

Link to this function

add_table_source(ml, source, data, coordinates, opts \\ [])

View Source
@spec add_table_source(t(), String.t(), term(), coordinates_spec(), keyword()) :: t()

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"])
@spec glyphs(t(), String.t()) :: t()

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.

@spec light(
  t(),
  keyword()
) :: t()

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.

Link to this function

metadata(ml, key, value)

View Source
@spec metadata(t(), String.t(), String.t()) :: t()

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:".

@spec new(keyword()) :: t()

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.

@spec sprite(t(), String.t()) :: t()

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.

@spec terrain(
  t(),
  keyword()
) :: t()

Add 3D terrain to the map.

The source must have been previously added to the map.

See the docs for more details.

@spec to_spec(t()) :: spec()

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.

@spec transition(
  t(),
  keyword()
) :: t()

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.

Link to this function

update_layer(ml, id, opts)

View Source
@spec update_layer(t(), String.t(), keyword()) :: t()

Updates a layer that was already defined in the specification