Visualization functions

Healpix.jl uses RecipesBase to display maps. You need to import Plots in order to display maps, using the plot functions. Maps are internally treated as heatmaps, so your backend should support this kind of visualization: at the moment, this is true for GR, PlotLy and PyPlot.

using Healpix
using Plots
pyplot()  # hide

nside = 8
m = HealpixMap{Float64, RingOrder}(nside)
m.pixels[:] = 1:length(m.pixels)
plot(m)
savefig(joinpath("images", "mollweide.png")) # hide

A call to plot can provide two additional arguments:

A carthographic projection (see below).
A dictionary containing parameters to be used by the carthographic projection.

The following example displays the same map in orthographic coordinates:

plot(m, orthographic)
savefig(joinpath("images", "orthographic.png")) # hide

Cartographic projections

Plotting is based on project, which takes a map as input and produces a 2-D bitmap containing a representation of the map suitable to be shown using Plots.

Although the easiest way to plot a map is to use plot, project might be suitable in those cases where you are just interested in a 2D bitmap. It requires a inverse projection function (mapping the 2D plane to a point on the sphere) and the size of the bitmap, and it returns three values:

A 2-D bitmap containing the color level of each pixel. Unseen pixels (e.g., those falling outside the ellipse in a Mollweide projection) are marked as NaN, as well as unseen pixels;
A 2-D bitmap of Bool values, telling which pixels in the map are masked, i.e., they are marked as UNSEEN, NaN or missing in the Healpix map;
A Bool flag telling if there is any masked value in the mask (2nd return value, see above). This parameter is returned to optimize calls to plot, but it is obviously redundant.

Consider this example:

using Healpix

m = HealpixMap{Float64, RingOrder}(1)
# Plot the map on a 20×20 bitmap using an
# equirectangular projection
image, mask, maskflag = project(equiprojinv, m, 20, 20)

(Float32[0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0], Bool[0 0 … 0 0; 0 0 … 0 0; … ; 0 0 … 0 0; 0 0 … 0 0], false)

A number of parameters can be passed to project, in order to taylor the representation. They must not be passed as keyword arguments, because this would clash with the way plot recipes work; instead, you must use a dictionary:

# Return a 2-D bitmap of 16-bit floating-point values
image, _, _ = project(equiprojinv, m, 20, 20,
                      Dict(:desttype => Float16))

(Float16[0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0], Bool[0 0 … 0 0; 0 0 … 0 0; … ; 0 0 … 0 0; 0 0 … 0 0], false)

The following dictionary keys are available:

:desttype: type used for the pixels in the 2-D bitmap returned by project. Default is Float32;
:unseen: the value marking pixels as unseen, i.e., masked. The default is -1.6375e+30, to preserve compatibility with other Healpix libraries.
:center: currently this is used only with orthographic projections. It specifies the coordinates of the center of the image (colatitude and longitude, both in radians).

Healpix.project — Function

project(invprojfn, m::HealpixMap{T, O, AA}, bmpwidth, bmpheight; kwargs...)

Return a 2D bitmap (array) containing a cartographic projection of the map and a 2D bitmap containing a boolean mask. The size of the bitmap is bmpwidth×bmpheight pixels. The function projfn must be a function which accepts as input two parameters x and y (numbers between -1 and 1).

The following keywords can be used in the call:

center: 2-tuple specifying the location (colatitude, longitude) of the sky point that is to be placed in the middle of the image (in radians)
unseen: by default, Healpix maps use the value -1.6375e+30 to mark unseen pixels. You can specify a different value using this keyword. This should not be used in common applications.

Return a Array{Union{Missing, Float32}} containing the intensity of each pixel. Pixels falling outside the projection are marked as NaN, and unseen pixels are marked as missing.

source

Projection functions

Functions mollweide, equirectangular, and orthographic can be passed as parameters to plot.

Healpix.mollweide — Function

mollweide(m::HealpixMap{T, O, AA}, projparams = Dict()) where {T <: Number, O, AA}

High-level wrapper around project for Mollweide projections.

The following parameters can be set in the projparams dictionary:

width: width of the image, in pixels (default: 720 pixels)
height: height of the image, in pixels; if not specified, it will be assumed to be equal to width

source

Healpix.equirectangular — Function

equirectangular(m::HealpixMap{T,O,AA}; kwargs...) where {T <: Number, O, AA}

High-level wrapper around project for equirectangular projections.

source

Healpix.orthographic — Function

orthographic(m::HealpixMap{T,O}, projparams = Dict()) where {T <: Number,O <: Order}

High-level wrapper around project for orthographic projections.

The following parameters can be set in the projparams dictionary:

width: width of the image, in pixels (default: 720 pixels)
height: height of the image, in pixels; if not specified, it will be assumed to be equal to width
center: position of the pixel in the middle of the left globe (latitude and longitude).

source

Healpix.orthographic2 — Function

orthographic2(m::HealpixMap{T, O, AA}, projparams = Dict()) where {T <: Number, O, AA}

High-level wrapper around project for stereo orthographic projections.

The following parameters can be set in the projparams dictionary:

width: width of the image, in pixels (default: 720 pixels)
height: height of the image, in pixels; if not specified, it will be assumed to be equal to width
center: position of the pixel in the middle of the left globe (latitude and longitude). Default is (0, 0).

source

Healpix.gnomonic — Function

gnomonic(m::HealpixMap{T, O, AA}, projparams = Dict()) where {T <: Number, O, AA}

High-level wrapper around project for gnomonic projections.

The following parameters can be set in the projparams dictionary:

width: width of the image, in pixels (default: 720 pixels)
height: height of the image, in pixels; if not specified, it will be assumed to be equal to width
center: position and orientation of the pixel in the middle. It is a 3-element tuple containing:
1. The latitude of the pixel, in radians
2. The longitude of the pixel, in radians
3. The rotation to be applied to the image, in radians
fov_rad: size of the image along the x and y axes, in radians (default: 15°)

Example

plot(m, gnomonic, Dict(:fov_rad = deg2rad(1.5), :center = (0, 0, deg2rad(45))))

source

They are based on inverse projection functions, i.e., functions that take a point in the plane $[-1, 1] \times [-1, 1]$ and return a tuple (Bool, Number, Number), where the first Boolean is true if the point falls within the projection, and the other two numbers are the latitude and longitude in radians.

Healpix.mollweideprojinv — Function

mollweideprojinv(x, y)

Inverse Mollweide projection. Given a point (x, y) on the plane, with x ∈ [-1, 1], y ∈ [-1, 1], return a 3-tuple of type (Bool, Number, Number). The boolean specifies if (x, y) falls within the map (true) or not (false), the second and third arguments are the latitude and longitude in radians.

source

Healpix.equiprojinv — Function

equiprojinv(x, y)

Inverse equirectangular projection. Given a point (x, y) on the plane [-1, 1] × [-1, 1], return a tuple (Bool, Number, Number) where the first Boolean is a flag telling if the point falls within the projection (true) or not (false), and the two numbers are the latitude and longitude in radians.

source

Healpix.orthoinv — Function

orthoinv(x, y, ϕ1, λ0)

Inverse orthographic projection centered on (ϕ1, λ0). Given a point (x, y) on the plane, with x ∈ [-1, 1], y ∈ [-1, 1], return a 3-tuple of type (Bool, Number, Number). The boolean specifies if (x, y) falls within the map (true) or not (false), the second and third arguments are the latitude and longitude in radians.

source

Healpix.ortho2inv — Function

function ortho2inv(x, y, ϕ1, λ0)

Inverse stereo orthographic projection centered on (ϕ1, λ0). Given a point (x, y) on the plane, with x ∈ [-1, 1], y ∈ [-1, 1], return a 3-tuple of type (Bool, Number, Number). The boolean specifies if (x, y) falls within the map (true) or not (false), the second and third arguments are the latitude and longitude in radians.

source

Healpix.gnominv — Function

function gnominv(x, y, ϕ1, λ0, fov_rad)

Gnomonic projection centered on (ϕ1, λ0), with a field of view equal to fov_rad (in radians). Given a point (x, y) on the plane, with x ∈ [-1, 1], y ∈ [-1, 1], return a 3-tuple of type (Bool, Number, Number). The boolean specifies if (x, y) falls within the map (true) or not (false), the second and third arguments are the latitude and longitude in radians.

source

The direct project functions are available too.

Healpix.equiproj — Function

equiproj(lat, lon)

Equirectangular projection. Given the latitude lat (in radians) and the longitude (in radians), return a tuple (Bool, Number, Number) where the first Boolean is a flag telling if the point falls within the projection (true) or not (false), and the two numbers are the x and y coordinates of the point on the projection plane (both are in the range [−1, 1]).

source

Healpix.mollweideproj — Function

mollweideproj(lat, lon)

Mollweide projection. Given the latitude lat (in radians) and the longitude (in radians), return a tuple (Bool, Number, Number) where the first Boolean is a flag telling if the point falls within the projection (true) or not (false), and the two numbers are the x and y coordinates of the point on the projection plane (both are in the range [−1, 1]).

source