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
gr()  # Use the GR backend

nside = 8
m = Map{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 = Map{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[false false … false false; false false … false false; … ; false false … false false; false false … false false], 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[false false … false false; false false … false false; … ; false false … false false; false false … false false], 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::Map{T, O}, bmpwidth, bmpheight; kwargs...) where {T <: Number, O <: Order}

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::Map{T,O}, projparams = Dict()) where {T <: Number,O <: Order}

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::Map{T,O}; kwargs...) where {T <: Number, O <: Order}

High-level wrapper around project for equirectangular projections.

source

Healpix.orthographic — Function.

orthographic(m::Map{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::Map{T,O}, projparams = Dict()) where {T <: Number,O <: Order}

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::Map{T,O}, projparams = Dict()) where {T <: Number,O <: Order}

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

mollweideprojinv
equiprojinv
orthoinv
ortho2inv
gnominv