
Summary: This introduction shows the differences between Geo and Mapbox based geographical charts.
Plotly and therefore Plotly.NET supports two different kinds of maps:
-
Mapbox maps are tile-based maps. If your figure is created with a Chart.*Mapbox
function or otherwise contains one or more traces of type scattermapbox
,
choroplethmapbox
or densitymapbox
, the layout.mapbox object in your figure contains configuration information for the map itself.
-
Geo maps are outline-based maps. If your figure is created with a Chart.ScatterGeo
, Chart.PointGeo
, Chart.LineGeo
or Chart.Choropleth
function or
otherwise contains one or more traces of type scattergeo
or choropleth
, the layout.geo object in your figure contains configuration information for the map itself.
This page documents Mapbox tile-based maps, and the Geo map documentation describes how to configure outline-based maps
Mapbox tile maps are composed of various layers, of three different types:
- the
style
property of the Mapbox
object defines is the lowest layers, also known as your "base map"
- The various traces in data are by default rendered above the base map (although this can be controlled via the below attribute).
- the
layers
property of the Mapbox
object is an array that defines more layers that are by default rendered above the traces in data (although this can also be controlled via the below attribute).
a Mapbox
object where these properties can be set can be initialized via Mapbox.init
. To use it in a chart, use the Chart.withMapbox
function:
open Plotly.NET
open Plotly.NET.LayoutObjects
// a simple Mapbox with a OpenStreetMap base layer.
let mb = Mapbox.init (Style = StyleParam.MapboxStyle.OpenStreetMap)
let baseLayerOnly =
Chart.PointMapbox(lonlat = []) // deliberately empty chart to show the base map only
|> Chart.withMapbox mb // add the mapBox
The word "mapbox" in the trace names and layout.mapbox refers to the Mapbox GL JS open-source library, which is integrated into Plotly.NET.
If your basemap uses data from the Mapbox service, then you will need to register for a free account at https://mapbox.com/
and obtain a Mapbox Access token.
This token should be provided via the AccessToken
property:
let mbWithToken =
Mapbox.init (Style = StyleParam.MapboxStyle.OpenStreetMap, AccessToken = "your_token_here")
If your base map does not use data from the Mapbox service, you do not need to register for a Mapbox account.
WhiteBG
yields an empty white canvas which results in no external HTTP requests
- The plotly presets yield maps composed of raster tiles from various public tile servers which do not require signups or access tokens
- The Mapbox presets yield maps composed of vector tiles from the Mapbox service, and do require a Mapbox Access Token or an on-premise Mapbox installation.
-
Use
StyleParam.MapboxStyle.Custom
for:
The accepted values for the style
property of the Mapbox
object are represented in StyleParam.MapboxStyle
:
type MapboxStyle =
// plotly presets, no token needed
| WhiteBG
| OpenStreetMap
| CartoPositron
| CartoDarkmatter
| StamenTerrain
| StamenToner
| StamenWatercolor
// Mapbox presets, you might need a free token
| MapboxBasic
| MapboxStreets
| MapboxOutdoors
| MapboxLight
| MapboxDark
| MapboxSatellite
| MapboxSatelliteStreets
//Custom - provide custom maps
| Custom of string
namespace Plotly
namespace Plotly.NET
module Defaults
from Plotly.NET
<summary>
Contains mutable global default values.
Changing these values will apply the default values to all consecutive Chart generations.
</summary>
val mutable DefaultDisplayOptions: DisplayOptions
Multiple items
type DisplayOptions =
inherit DynamicObj
new: unit -> DisplayOptions
static member addAdditionalHeadTags: additionalHeadTags: XmlNode list -> (DisplayOptions -> DisplayOptions)
static member addDescription: description: XmlNode list -> (DisplayOptions -> DisplayOptions)
static member combine: first: DisplayOptions -> second: DisplayOptions -> DisplayOptions
static member getAdditionalHeadTags: displayOpts: DisplayOptions -> XmlNode list
static member getDescription: displayOpts: DisplayOptions -> XmlNode list
static member getPlotlyReference: displayOpts: DisplayOptions -> PlotlyJSReference
static member init: ?AdditionalHeadTags: XmlNode list * ?Description: XmlNode list * ?PlotlyJSReference: PlotlyJSReference -> DisplayOptions
static member initCDNOnly: unit -> DisplayOptions
...
--------------------
new: unit -> DisplayOptions
static member DisplayOptions.init: ?AdditionalHeadTags: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?Description: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?PlotlyJSReference: PlotlyJSReference -> DisplayOptions
type PlotlyJSReference =
| CDN of string
| Full
| Require of string
| NoReference
<summary>
Sets how plotly is referenced in the head of html docs.
</summary>
union case PlotlyJSReference.NoReference: PlotlyJSReference
namespace Plotly.NET.LayoutObjects
val mb: Mapbox
Multiple items
type Mapbox =
inherit DynamicObj
new: unit -> Mapbox
static member init: ?Domain: Domain * ?AccessToken: string * ?Style: MapboxStyle * ?Bounds: MapboxBounds * ?Center: (float * float) * ?Zoom: float * ?Bearing: float * ?Pitch: float * ?Layers: seq<MapboxLayer> -> Mapbox
static member style: ?Domain: Domain * ?AccessToken: string * ?Style: MapboxStyle * ?Bounds: MapboxBounds * ?Center: (float * float) * ?Zoom: float * ?Bearing: float * ?Pitch: float * ?Layers: seq<MapboxLayer> -> (Mapbox -> Mapbox)
<summary>Determines the style of the map shown in mapbox traces</summary>
--------------------
new: unit -> Mapbox
static member Mapbox.init: ?Domain: Domain * ?AccessToken: string * ?Style: StyleParam.MapboxStyle * ?Bounds: MapboxBounds * ?Center: (float * float) * ?Zoom: float * ?Bearing: float * ?Pitch: float * ?Layers: seq<MapboxLayer> -> Mapbox
module StyleParam
from Plotly.NET
type MapboxStyle =
| OpenStreetMap
| WhiteBG
| CartoPositron
| CartoDarkmatter
| StamenTerrain
| StamenToner
| StamenWatercolor
| MapboxBasic
| MapboxStreets
| MapboxOutdoors
...
member Convert: unit -> obj
override ToString: unit -> string
static member convert: (MapboxStyle -> obj)
static member toString: (MapboxStyle -> string)
<summary>
Defines the map layers that are rendered by default below the trace layers defined in `data`, which are themselves by default rendered below the layers defined in `layout.mapbox.layers`.
These layers can be defined either explicitly as a Mapbox Style object which can contain multiple layer definitions that load data from any public or private Tile Map Service (TMS or XYZ) or Web Map Service (WMS) or implicitly by using one of the built-in style objects which use WMSes which do not require any access tokens,
or by using a default Mapbox style or custom Mapbox style URL, both of which require a Mapbox access token Note that Mapbox access token can be set in the `accesstoken` attribute or in the `mapboxAccessToken` config option.
Mapbox Style objects are of the form described in the Mapbox GL JS documentation available at https://docs.mapbox.com/mapbox-gl-js/style-spec The built-in plotly.js styles objects are: open-street-map, white-bg, carto-positron, carto-darkmatter, stamen-terrain, stamen-toner, stamen-watercolor
The built-in Mapbox styles are: basic, streets, outdoors, light, dark, satellite, satellite-streets Mapbox style URLs are of the form: mapbox://mapbox.mapbox-<name>-<version>
</summary>
union case StyleParam.MapboxStyle.OpenStreetMap: StyleParam.MapboxStyle
val baseLayerOnly: GenericChart.GenericChart
type Chart =
static member AnnotatedHeatmap: zData: seq<#seq<'a1>> * annotationText: seq<#seq<string>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?X: seq<'a3> * ?MultiX: seq<seq<'a3>> * ?XGap: int * ?Y: seq<'a4> * ?MultiY: seq<seq<'a4>> * ?YGap: int * ?Text: 'a5 * ?MultiText: seq<'a5> * ?ColorBar: ColorBar * ?ColorScale: Colorscale * ?ShowScale: bool * ?ReverseScale: bool * ?ZSmooth: SmoothAlg * ?Transpose: bool * ?UseWebGL: bool * ?ReverseYAxis: bool * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a3 :> IConvertible and 'a4 :> IConvertible and 'a5 :> IConvertible) + 1 overload
static member Area: x: seq<#IConvertible> * y: seq<#IConvertible> * ?ShowMarkers: bool * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: seq<MarkerSymbol> * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?FillColor: Color * ?FillPatternShape: PatternShape * ?FillPattern: Pattern * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'a2 :> IConvertible) + 1 overload
static member Bar: values: seq<#IConvertible> * ?Keys: seq<'a1> * ?MultiKeys: seq<seq<'a1>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerPatternShape: PatternShape * ?MultiMarkerPatternShape: seq<PatternShape> * ?MarkerPattern: Pattern * ?Marker: Marker * ?Base: #IConvertible * ?Width: 'a4 * ?MultiWidth: seq<'a4> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a2 :> IConvertible and 'a4 :> IConvertible) + 1 overload
static member BoxPlot: ?X: seq<'a0> * ?MultiX: seq<seq<'a0>> * ?Y: seq<'a1> * ?MultiY: seq<seq<'a1>> * ?Name: string * ?ShowLegend: bool * ?Text: 'a2 * ?MultiText: seq<'a2> * ?FillColor: Color * ?MarkerColor: Color * ?Marker: Marker * ?Opacity: float * ?WhiskerWidth: float * ?BoxPoints: BoxPoints * ?BoxMean: BoxMean * ?Jitter: float * ?PointPos: float * ?Orientation: Orientation * ?OutlineColor: Color * ?OutlineWidth: float * ?Outline: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?Notched: bool * ?NotchWidth: float * ?QuartileMethod: QuartileMethod * ?UseDefaults: bool -> GenericChart (requires 'a0 :> IConvertible and 'a1 :> IConvertible and 'a2 :> IConvertible) + 2 overloads
static member Bubble: x: seq<#IConvertible> * y: seq<#IConvertible> * sizes: seq<int> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: seq<MarkerSymbol> * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'a2 :> IConvertible) + 1 overload
static member Candlestick: ``open`` : seq<#IConvertible> * high: seq<#IConvertible> * low: seq<#IConvertible> * close: seq<#IConvertible> * ?X: seq<'a4> * ?MultiX: seq<seq<'a4>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?Text: 'a5 * ?MultiText: seq<'a5> * ?Line: Line * ?IncreasingColor: Color * ?Increasing: FinanceMarker * ?DecreasingColor: Color * ?Decreasing: FinanceMarker * ?WhiskerWidth: float * ?ShowXAxisRangeSlider: bool * ?UseDefaults: bool -> GenericChart (requires 'a4 :> IConvertible and 'a5 :> IConvertible) + 2 overloads
static member Column: values: seq<#IConvertible> * ?Keys: seq<'a1> * ?MultiKeys: seq<seq<'a1>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerPatternShape: PatternShape * ?MultiMarkerPatternShape: seq<PatternShape> * ?MarkerPattern: Pattern * ?Marker: Marker * ?Base: #IConvertible * ?Width: 'a4 * ?MultiWidth: seq<'a4> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a2 :> IConvertible and 'a4 :> IConvertible) + 1 overload
static member Contour: zData: seq<#seq<'a1>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?X: seq<'a2> * ?MultiX: seq<seq<'a2>> * ?Y: seq<'a3> * ?MultiY: seq<seq<'a3>> * ?Text: 'a4 * ?MultiText: seq<'a4> * ?ColorBar: ColorBar * ?ColorScale: Colorscale * ?ShowScale: bool * ?ReverseScale: bool * ?Transpose: bool * ?ContourLineColor: Color * ?ContourLineDash: DrawingStyle * ?ContourLineSmoothing: float * ?ContourLine: Line * ?ContoursColoring: ContourColoring * ?ContoursOperation: ConstraintOperation * ?ContoursType: ContourType * ?ShowContourLabels: bool * ?ContourLabelFont: Font * ?Contours: Contours * ?FillColor: Color * ?NContours: int * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a2 :> IConvertible and 'a3 :> IConvertible and 'a4 :> IConvertible)
static member Funnel: x: seq<#IConvertible> * y: seq<#IConvertible> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?Width: float * ?Offset: float * ?Text: 'a2 * ?MultiText: seq<'a2> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?Orientation: Orientation * ?AlignmentGroup: string * ?OffsetGroup: string * ?MarkerColor: Color * ?MarkerOutline: Line * ?Marker: Marker * ?TextInfo: TextInfo * ?ConnectorLineColor: Color * ?ConnectorLineStyle: DrawingStyle * ?ConnectorFillColor: Color * ?ConnectorLine: Line * ?Connector: FunnelConnector * ?InsideTextFont: Font * ?OutsideTextFont: Font * ?UseDefaults: bool -> GenericChart (requires 'a2 :> IConvertible)
static member Heatmap: zData: seq<#seq<'a1>> * ?X: seq<'a2> * ?MultiX: seq<seq<'a2>> * ?Y: seq<'a3> * ?MultiY: seq<seq<'a3>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?XGap: int * ?YGap: int * ?Text: 'a4 * ?MultiText: seq<'a4> * ?ColorBar: ColorBar * ?ColorScale: Colorscale * ?ShowScale: bool * ?ReverseScale: bool * ?ZSmooth: SmoothAlg * ?Transpose: bool * ?UseWebGL: bool * ?ReverseYAxis: bool * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a2 :> IConvertible and 'a3 :> IConvertible and 'a4 :> IConvertible) + 1 overload
...
static member Chart.PointMapbox: lonlat: seq<#System.IConvertible * #System.IConvertible> * ?Name: string * ?MapboxStyle: StyleParam.MapboxStyle * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'c * ?MultiText: seq<'c> * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: seq<StyleParam.TextPosition> * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: seq<StyleParam.MarkerSymbol> * ?Marker: TraceObjects.Marker * ?Below: string * ?EnableClustering: bool * ?Cluster: MapboxCluster * ?UseDefaults: bool -> GenericChart.GenericChart (requires 'c :> System.IConvertible)
static member Chart.PointMapbox: longitudes: seq<#System.IConvertible> * latitudes: seq<#System.IConvertible> * ?Name: string * ?MapboxStyle: StyleParam.MapboxStyle * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: seq<StyleParam.TextPosition> * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: seq<StyleParam.MarkerSymbol> * ?Marker: TraceObjects.Marker * ?Below: string * ?EnableClustering: bool * ?Cluster: MapboxCluster * ?UseDefaults: bool -> GenericChart.GenericChart (requires 'a2 :> System.IConvertible)
static member Chart.withMapbox: mapbox: Mapbox * ?Id: int -> (GenericChart.GenericChart -> GenericChart.GenericChart)
module GenericChart
from Plotly.NET
<summary>
Module to represent a GenericChart
</summary>
val toChartHTML: gChart: GenericChart.GenericChart -> string
val mbWithToken: Mapbox
type MapboxStyle =
| WhiteBG
| OpenStreetMap
| CartoPositron
| CartoDarkmatter
| StamenTerrain
| StamenToner
| StamenWatercolor
| MapboxBasic
| MapboxStreets
| MapboxOutdoors
...
union case MapboxStyle.WhiteBG: MapboxStyle
union case MapboxStyle.OpenStreetMap: MapboxStyle
union case MapboxStyle.CartoPositron: MapboxStyle
union case MapboxStyle.CartoDarkmatter: MapboxStyle
union case MapboxStyle.StamenTerrain: MapboxStyle
union case MapboxStyle.StamenToner: MapboxStyle
union case MapboxStyle.StamenWatercolor: MapboxStyle
union case MapboxStyle.MapboxBasic: MapboxStyle
union case MapboxStyle.MapboxStreets: MapboxStyle
union case MapboxStyle.MapboxOutdoors: MapboxStyle
union case MapboxStyle.MapboxLight: MapboxStyle
union case MapboxStyle.MapboxDark: MapboxStyle
union case MapboxStyle.MapboxSatellite: MapboxStyle
union case MapboxStyle.MapboxSatelliteStreets: MapboxStyle
union case MapboxStyle.Custom: string -> MapboxStyle
Multiple items
val string: value: 'T -> string
<summary>Converts the argument to a string using <c>ToString</c>.</summary>
<remarks>For standard integer and floating point values the and any type that implements <c>IFormattable</c><c>ToString</c> conversion uses <c>CultureInfo.InvariantCulture</c>. </remarks>
<param name="value">The input value.</param>
<returns>The converted string.</returns>
<example id="string-example"><code lang="fsharp"></code></example>
--------------------
type string = System.String
<summary>An abbreviation for the CLI type <see cref="T:System.String" />.</summary>
<category>Basic Types</category>