API reference

This page lists all documented functions, types, and macros in GeoMakie.

GeoMakie.GeoAxis Type

GeoMakie.GeoAxis <: Block

No docstring defined.

Attributes

(type ?GeoMakie.GeoAxis.x in the REPL for more information about attribute x)

alignmode, aspect, autolimitaspect, dest, fonts, halign, height, limits, panbutton, source, subtitle, subtitlecolor, subtitlefont, subtitlegap, subtitlelineheight, subtitlesize, subtitlevisible, tellheight, tellwidth, title, titlealign, titlecolor, titlefont, titlegap, titlelineheight, titlesize, titlevisible, valign, width, xautolimitmargin, xaxisposition, xgridcolor, xgridstyle, xgridvisible, xgridwidth, xlabel, xlabelcolor, xlabelfont, xlabelpadding, xlabelrotation, xlabelsize, xlabelvisible, xminorgridcolor, xminorgridstyle, xminorgridvisible, xminorgridwidth, xminortickalign, xminortickcolor, xminorticks, xminorticksize, xminorticksvisible, xminortickwidth, xpankey, xpanlock, xrectzoom, xreversed, xscale, xtickalign, xtickcolor, xtickformat, xticklabelalign, xticklabelcolor, xticklabelfont, xticklabelpad, xticklabelrotation, xticklabelsize, xticklabelspace, xticklabelsvisible, xticks, xticksize, xticksvisible, xtickwidth, xzoomkey, xzoomlock, yautolimitmargin, yaxisposition, ygridcolor, ygridstyle, ygridvisible, ygridwidth, ylabel, ylabelcolor, ylabelfont, ylabelpadding, ylabelrotation, ylabelsize, ylabelvisible, yminorgridcolor, yminorgridstyle, yminorgridvisible, yminorgridwidth, yminortickalign, yminortickcolor, yminorticks, yminorticksize, yminorticksvisible, yminortickwidth, ypankey, ypanlock, yrectzoom, yreversed, yscale, ytickalign, ytickcolor, ytickformat, yticklabelalign, yticklabelcolor, yticklabelfont, yticklabelpad, yticklabelrotation, yticklabelsize, yticklabelspace, yticklabelsvisible, yticks, yticksize, yticksvisible, ytickwidth, yzoomkey, yzoomlock

GeoMakie.GeoTicks Type

julia

GeoTicks(; multiple = 12, threshold = 3, alternate_tickfinder = Makie.WilkinsonTicks(5; k_min = 3))

A tick finder optimized for geographic axes.

Keyword arguments

multiple: The number of ticks to keep spaced, with a minimum spacing of 1.
threshold: The minimum distance between ticks, before the alternate_tickfinder is used.
alternate_tickfinder: The tick finder to use if the range is not large enough to keep the multiple ticks.

Behaviour

The tickfinder has three regimes, defined by the distance between the minimum and maximum values.

: Use the alternate_tickfinder to find ticks.
$Misplaced &$ : -dvmin:30:dvmax
All other cases: Find ticks in the range mini:step:maxi, where step is the closest multiple of (maxi-mini)/multiple to dmaxi.

GeoMakie.GeodesyGlobeTransform Type

julia

struct GeodesyGlobeTransform{CoordType, T} <: GlobeTransform

Geodesy.jl based transformation to the dest ellipsoid, for source coordinates of type CoordType (e.g. Geodesy.LLA, Geodesy.UTM, Geodesy.UTMZ).

GeoMakie.GlobeAxis Type

GeoMakie.GlobeAxis <: Block

julia

GlobeAxis(layout_position; attrs...)

Warning

GlobeAxis is experimental and we reserve the right to break the API at any time, even without a breaking release!

Use with care (but do use it, it's fun!)

GlobeAxis is a 3-dimensional, geographic axis that plots your data on the Earth as a globe. It's similar to what you see if you zoom out in Google Maps, but without the ability to switch to web-mercator when zooming in.

All data is transformed to cartesian (X, Y, Z) space, and inputs are (by default) interpreted as (long, lat, [alt]).

You can change what the inputs mean by passing a different source CRS (see the docs) as a keyword argument to each plot you make.

Interaction is the same as Makie's Axis3, with the exception that the camera is by default locked to always view the origin, and translation is blocked. This makes scrolling a lot easier, and since the camera is a Camera3D you can always use that directly.

Plot-specific keywords

GlobeAxis introduces some keywords you can use in plot functions to customize what they do. These are applicable to any plot, since they operate on the axis level.

Currently, these attributes are:

source = "+proj=longlat +datum=wgs84": set the source CRS, similarly to that attribute in GeoAxis.
zlevel = 0: set the default Z level / altitude before transformation, i.e., an offset from the default 0. This is very useful when you want to layer plots on top of each other. In general, if you use the default destination datum, a value of 20_000 is where zlevel starts to be visible. Of course, for simple displacement to correct z-fighting issues, values of 10 or more should suffice.
reset_limits = true: whether the plot should trigger a limit reset when plotted. Useful if you are adding plots during interactive use.

Important attributes

source = "+proj=longlat +datum=wgs84 +type=crs": set the default source CRS of the projection. This is always normalized to the XY axis order, no matter what you write here. This can also be overridden at any point by the source attribute to a plot.
lights = automatic: lights to install on the underlying scene. automatic installs a camera-locked three-point rig (key/fill/back) plus a low ambient — chosen so plots with shading enabled stay visible whichever side of the globe you're looking at. Pass a Vector{<:Makie.AbstractLight} to override; include an AmbientLight in the vector if you want non-zero ambient. Pass [] for a fully dark scene. The attribute is observable, so you can mutate it after construction (e.g. ga.lights[] = [...] or ga.lights[] = automatic to restore the default).
show_axis = true: whether to show the LScene's axis, or not.

Attributes

(type ?GeoMakie.GlobeAxis.x in the REPL for more information about attribute x)

alignmode, backgroundalpha, backgroundcolor, backgroundradius, backgroundtransparency, backgroundvisible, camera_altitude, camera_longlat, center, dest, fonts, halign, height, lights, show_axis, source, subtitle, subtitlecolor, subtitlefont, subtitlegap, subtitlelineheight, subtitlesize, subtitlevisible, tellheight, tellwidth, title, titlealign, titlecolor, titlefont, titlegap, titlelineheight, titlesize, titlevisible, valign, width, xgridcolor, xgridstyle, xgridvisible, xgridwidth, xminorgridcolor, xminorgridstyle, xminorgridvisible, xminorgridwidth, xminortickalign, xminortickcolor, xminorticks, xminorticksize, xminorticksvisible, xminortickwidth, xscale, xtickalign, xtickcolor, xtickformat, xticklabelalign, xticklabelcolor, xticklabelfont, xticklabelpad, xticklabelrotation, xticklabelsize, xticklabelspace, xticklabelsvisible, xticks, xticksize, xticksvisible, xtickwidth, ygridcolor, ygridstyle, ygridvisible, ygridwidth, yminorgridcolor, yminorgridstyle, yminorgridvisible, yminorgridwidth, yminortickalign, yminortickcolor, yminorticks, yminorticksize, yminorticksvisible, yminortickwidth, yscale, ytickalign, ytickcolor, ytickformat, yticklabelalign, yticklabelcolor, yticklabelfont, yticklabelpad, yticklabelrotation, yticklabelsize, yticklabelspace, yticklabelsvisible, yticks, yticksize, yticksvisible, ytickwidth, zscale

GeoMakie.GlobeTransform Type

julia

abstract type GlobeTransform

The supertype for all globe transforms.

All subtypes must be callable with a Point, and have a field zlevel.

Construct via create_globe_transform. Used in GlobeAxis.

GeoMakie.MeshImage Type

MeshImage is the plot type associated with plotting function meshimage. Check the docstring for meshimage for further information.

GeoMakie.ProjGlobeTransform Type

julia

struct ProjGlobeTransform <: GlobeTransform
ProjGlobeTransform(dest, src, zlevel)

Proj.jl based transformation to the dest ellipsoid (from Geodesy.jl).

GeoMakie.closest_multiple Method

julia

closest_multiple(M, N)

Find the closest integer multiple of M to N.

GeoMakie.coastlines Method

julia

coastlines(ga::GeoAxis)

Split coastline contours when ga.dest includes a "+lon_0" specification.

GeoMakie.coastlines Method

julia

coastlines([scale::Int = 110])

Loads Natural Earth ^[1] coastline data as GeometryBasics.jl geometries. scale may be one of 110, 50, or 10.

By default, a scale of 110m is used, for which data is shipped with GeoMakie. To use other scales, NaturalEarth.jl requires an Internet connection to download the relevant data.

GeoMakie.create_globe_transform Method

julia

create_globe_transform(dest, src, zlevel)

Create a GlobeTransform that converts coordinates from the src CRS into geocentric Cartesian (ECEF) coordinates on the ellipsoid dest, offsetting each point's altitude by zlevel.

Returns a GeodesyGlobeTransform when dest is a Geodesy.Ellipsoid and src is passed as a type (dispatched on src::Type). In practice src must be one of the coordinate types for which a GeodesyGlobeTransform constructor exists (Geodesy.LLA, Geodesy.UTM, Geodesy.UTMZ); other types raise a MethodError. Otherwise returns a Proj.jl-based ProjGlobeTransform.

GeoMakie.create_transform Method

julia

create_transform(dest, source)

Creates a transformation going from source to dest with the axis order set to XYZ. This can take in Strings, GFT objects, or Observables, and the output type mirrors the input type - either a Transformation or an Observable{Transformation}.

GeoMakie.earth Method

julia

earth()

Loads the Natural Earth ^[1:1] 50m raster illustration of Earth as an image. Doesn't support scale as of yet, but that's coming soon!

GeoMakie.geo2basic Method

julia

geo2basic(input)

Takes any GeoInterface-compatible structure, and returns its equivalent in the GeometryBasics.jl package, which Makie is built on.

Currently works for the following traits:

julia

- PointTrait
- LineTrait
- LineStringTrait
- PolygonTrait
- MultiPolygonTrait

GeoMakie.geoformat_ticklabels Method

julia

geoformat_ticklabels(nums::Vector)

A semi-intelligent formatter for geographic tick labels. Append "ᵒ" to the end of each tick label, to indicate degree.

This will check whether the ticklabel is an integer value (round(num) == num). If so, label as an Int (1 instead of 1.0) which looks a lot cleaner.

Example

julia

julia> geoformat_ticklabels([1.0, 1.1, 2.5, 25])
4-element Vector{String}:
 "1ᵒ"
 "1.1ᵒ"
 "2.5ᵒ"
 "25ᵒ"

GeoMakie.geom_to_bands Method

julia

geom_to_bands(geom; height = 100_000, base = 0)::Tuple{Vector{Point3d}, Vector{Point3d}}

Reduce a geometry to a NaN-separated list of points, and return a pair of vectors of points in the same CRS - one with z coordinate base, and one at z coordinate base +height.

Returns a tuple of (lower_band, upper_band).

This can be directly splatted into Makie's band! recipe, which will create a 3D band. Especially useful in GlobeAxis.

Accepts any GeoInterface-compatible geometry that is composed of curves (linestrings or linear rings) or a higher level structure composed of such.

So any Polygon, MultiPolygon, LineString, MultiLineString, etc., but also a vector of those, a table (from Tables.jl), or a feature collection.

Example

julia

julia> lb, ub = geom_to_bands(california, 50_000)
julia> band(lb, ub; color = :red)

GeoMakie.geoticks Method

julia

geoticks(dmini, dmaxi, mini, maxi; multiple, threshold, alternate_tickfinder)

A tick finder optimized for geographic axes.

Keyword arguments

multiple::Int = 12: The number of ticks to keep spaced, with a minimum spacing of 1.
threshold::Float64 = 3: The minimum distance between ticks, before the alternate_tickfinder is used.
alternate_tickfinder = Makie.WilkinsonTicks(5; k_min = 3): The tick finder to use if the range is not large enough to keep the multiple ticks.

Behaviour

The tickfinder has three regimes, defined by the distance between the minimum and maximum values.

: Use the alternate_tickfinder to find ticks.
$Misplaced &$ : -dvmin:30:dvmax
All other cases: Find ticks in the range mini:step:maxi, where step is the closest multiple of (maxi-mini)/multiple to dmaxi.

GeoMakie.gft2str Function

julia

gft2str(crs)::String

Return a PROJ-compatible string from a GeoFormatTypes CRS object.

GeoMakie.icosphere Function

julia

icosphere(n_refinements::Int = 2)

Create an icosphere with the specified number of refinements.

Returns a tuple containing a vector of points (vertices) and a vector of faces.

Usage examples

julia

vertices, faces = icosphere(2)
msh = GeometryBasics.Mesh(vertices, faces)
# you can now plot this however you like:
using GLMakie
wireframe(msh)

If you want to assign UV coordinates to the vertices, you can compute them from the vertices directly. In this case we'll map the UVs to a lon-lat equirectangular projection, with u going from 0 to 1 horizontally around the sphere, and v going from 0 to 1 vertically from the south pole to the north pole.

julia

# create the icosphere mesh
vertices, faces = icosphere(2)
# compute the UV coordinates
uvs = [Vec2{Float64}(atan(p[2], p[1]) / (2π) + 0.5, asin(p[3]) / π + 0.5) for p in vertices]

# create the mesh with UV coordinates
mesh = GeometryBasics.Mesh(GeometryBasics.meta(vertices; uv = uvs), faces)

GeoMakie.land Method

julia

land()

Loads Natural Earth ^[1:2] land polygon data as GeometryBasics.jl geometries. scale may be one of 110, 50, or 10.

By default, a scale of 110m is used, for which data is shipped with GeoMakie. To use other scales, NaturalEarth.jl requires an Internet connection to download the relevant data.

GeoMakie.meshimage Function

julia

meshimage([xs, ys,] img)
meshimage!(ax, [xs, ys,] img)

Plots an image on a mesh.

Useful for nonlinear transforms where a large image would take too long to transform usefully, but a smaller mesh can still represent the inherent nonlinearity of the space.

This basically plots a mesh with uv coordinates, and textures it by the provided image. Its conversion trait is ImageLike.

Tip

You can control the density of the mesh by the npoints attribute.

Plot type

The plot type alias for the meshimage function is MeshImage.

Attributes

alpha = 1.0 — The alpha value of the colormap or color attribute. Multiple alphas like in plot(alpha=0.2, color=(:red, 0.5)), will get multiplied.

clip_planes = @inherit clip_planes automatic — Clip planes offer a way to do clipping in 3D space. You can set a Vector of up to 8 Plane3f planes here, behind which plots will be clipped (i.e. become invisible). By default clip planes are inherited from the parent plot or scene. You can remove parent clip_planes by passing Plane3f[].

colormap = @inherit colormap :viridis — Sets the colormap that is sampled for numeric colors. PlotUtils.cgrad(...), Makie.Reverse(any_colormap) can be used as well, or any symbol from ColorBrewer or PlotUtils. To see all available color gradients, you can call Makie.available_gradients().

colorrange = automatic — The values representing the start and end points of colormap.

colorscale = identity — The color transform function. Can be any function, but only works well together with Colorbar for identity, log, log2, log10, sqrt, logit, Makie.pseudolog10, Makie.Symlog10, Makie.AsinhScale, Makie.SinhScale, Makie.LogScale, Makie.LuptonAsinhScale, and Makie.PowerScale.

depth_shift = 0.0 — Adjusts the depth value of a plot after all other transformations, i.e. in clip space, where -1 <= depth <= 1. This only applies to GLMakie and WGLMakie and can be used to adjust render order (like a tunable overdraw).

fxaa = true — Adjusts whether the plot is rendered with fxaa (fast approximate anti-aliasing, GLMakie only). Note that some plots implement a better native anti-aliasing solution (scatter, text, lines). For them fxaa = true generally lowers quality. Plots that show smoothly interpolated data (e.g. image, surface) may also degrade in quality as fxaa = true can cause blurring.

highclip = automatic — The color for any value above the colorrange.

inspectable = @inherit inspectable — Sets whether this plot should be seen by DataInspector. The default depends on the theme of the parent scene.

inspector_clear = automatic — Sets a callback function (inspector, plot) -> ... for cleaning up custom indicators in DataInspector.

inspector_hover = automatic — Sets a callback function (inspector, plot, index) -> ... which replaces the default show_data methods.

inspector_label = automatic — Sets a callback function (plot, index, position) -> string which replaces the default label generated by DataInspector.

lowclip = automatic — The color for any value below the colorrange.

model = automatic — Sets a model matrix for the plot. This overrides adjustments made with translate!, rotate! and scale!.

nan_color = :transparent — The color for NaN values.

npoints = 100 — The number of points the mesh should have per side. Can be an Integer or a 2-tuple of integers representing number of points per side.

overdraw = false — Controls if the plot will draw over other plots. This specifically means ignoring depth checks in GL backends

shading = NoShading — Sets the lighting algorithm used. Options are NoShading (no lighting), FastShading (AmbientLight + PointLight) or MultiLightShading (Multiple lights, GLMakie only). Note that this does not affect RPRMakie.

space = :data — Sets the transformation space for box encompassing the plot. See Makie.spaces() for possible inputs.

ssao = false — Adjusts whether the plot is rendered with ssao (screen space ambient occlusion). Note that this only makes sense in 3D plots and is only applicable with fxaa = true.

transformation = :automatic — Controls the inheritance or directly sets the transformations of a plot. Transformations include the transform function and model matrix as generated by translate!(...), scale!(...) and rotate!(...). They can be set directly by passing a Transformation() object or inherited from the parent plot or scene. Inheritance options include:

:automatic: Inherit transformations if the parent and child space is compatible
:inherit: Inherit transformations
:inherit_model: Inherit only model transformations
:inherit_transform_func: Inherit only the transform function
:nothing: Inherit neither, fully disconnecting the child's transformations from the parent

Another option is to pass arguments to the transform!() function which then get applied to the plot. For example transformation = (:xz, 1.0) which rotates the xy plane to the xz plane and translates by 1.0. For this inheritance defaults to :automatic but can also be set through e.g. (:nothing, (:xz, 1.0)).

transparency = false — Adjusts how the plot deals with transparency. In GLMakie transparency = true results in using Order Independent Transparency.

uv_transform = Makie.LinearAlgebra.I — Sets a transform for uv coordinates, which controls how the image is mapped to its rectangular area. The attribute can be I, scale::VecTypes{2}, (translation::VecTypes{2}, scale::VecTypes{2}), any of :rotr90, :rotl90, :rot180, :swapxy/:transpose, :flip_x, :flip_y, :flip_xy, or most generally a Makie.Mat{2, 3, Float32} or Makie.Mat3f as returned by Makie.uv_transform(). They can also be changed by passing a tuple (op3, op2, op1).

visible = true — Controls whether the plot gets rendered or not.

z_level = 0.0 — The z-coordinate given to each mesh point. Useful in 3D transformations.

GeoMakie.meshimage! Function

meshimage! is the mutating variant of plotting function meshimage. Check the docstring for meshimage for further information.

GeoMakie.to_multipoly Method

julia

to_multipoly(geom)

Convert a polygon, vector of polygons, multipolygon, or any GeoInterface-compatible geometry into a GeometryBasics.MultiPolygon. GeometryCollections are handled by extracting their polygon and multipolygon members and unioning them.

Makie.reset_limits! Method

julia

reset_limits!(axis; xauto = true, yauto = true)

Resets the axis limits depending on the value of axis.limits. If one of the two components of limits is nothing, that value is either copied from the targetlimits if xauto or yauto is false, respectively, or it is determined automatically from the plots in the axis. If one of the components is a tuple of two numbers, those are used directly.

Makie.tightlimits! Method

julia

tightlimits!(la::Axis)

Sets the autolimit margins to zero on all sides.

Made with Natural Earth. Free vector and raster map data at naturalearthdata.com. ↩︎ ↩︎ ↩︎